Commenting on Artifacts By: Scott Mackay Date: Fall 2009

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

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?

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

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

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?

Questions, Contact Information