1. Commenting on Artifacts
By: Scott Mackay
Date: Fall 2009

2. Constructive Reviewing – by Peers
Turn on “Track Changes”
This will record who you are & what you edit
Perform a constructive document review
If something is wrong, fix it directly
If you have an alternate approach, suggest it
If something is missing, add it
Use “comments” feature only if needed
If you think something is wrong, say why you think it is wrong
Help move the artifact toward completion
with minimum review cycles

3. Non-Constructive Comments
Non-Constructive comments cause delays – You need to give the information needed to take action.
Examples of non-constructive comments:
This is wrong, fix it immediately!
I don’t think this part is right
Where can I learn more about this?
I can think of other ways to do this
Is there a better way than this?
Call me and we can discuss this
Where did this data come from?
That’s not how we do it today
The system can’t do any of these things today
I gave you that answer a few weeks ago
Do not make non-constructive comments!
Given the information in the example comments above, what would your next step be?

4. Suggest the correction or fix it
Don’t present problems, recommend solutions!
Determine the solution and submit (or make) the recommended change
If you know the answer, don’t keep it a secret
Passing the problem to other people only causes delays and can cause details to be lost (wrong solution gets implemented)
If you can’t solve it, get it to the right person
Do not start non-constructive actions

5. Right Place, Right Person
Keep comments appropriate for the artifact
Requirement comments go in Requirements Artifacts
Analysis comments go in Analysis Artifacts
Design comments go in Design Artifacts
Send ‘ad hoc” comments and questions to the Author of the artifact
Go to the right person first to avoid delays and un-needed intermediate steps

6. Classic Comments  WWYD?
This use case is written entirely from the users prospective, I have know idea how it will be implemented. Please explain this to me.
Miscellaneous? That could be anything!
This opens Pandora’s Box!
This will be tough to implement
I have no comment on this
Why wasn’t I asked about this earlier?
The storyboard looks like a comic strip
Wouldn’t this require a change?
This is going to get a bunch of readers tied up in a knot.
My team reviewed all 1350 requirements and found 2 to be wrong. When will these be fixed?
WWYD?

7. Questions, Contact Information