Saturday, July 11, 2009

Questions for reviews

Are you also a person who is able to find holes in functional/ technical designs and other documents? When reading a paper do you sometimes have the feeling something is missing?

I was triggered by this question because recently I was able to tell people I missed something in a functional design. Not that it was a bad design, how can it be as developers were able to write a technical design based on demanded functionality. Also were testers able to test the functionality. So was it actually that bad? No, we managed to reach our goal.

Reviews are introduced to avoid errors and changes in a later stage of development. There are lots of books written to explain which type of reviews can be done and also how to do them. I think certain issues in DUR (Documents Under Review) can be avoided also on an earlier stage. In some organizations this is mainly done by using writing guidelines and templates. Only this doesn't guarantee information is missing in those documents.

Before a document is handed over for review you can also perform some initial checks. For this purpose I post here an idea I have about this, perhaps it might help you also.
Obviously a checklist would be appropriate. The disadvantage I see of using a checklist is people stop thinking. Under time pressure they even might answer every check with "YES" so the process can continue.

Instead of using checks you might use questions to gain information about the document and how you managed to create the document. The following points can be used for questioning Functional Designs. I think it also might be used for other documents as well. As often, list can never be complete and should never be used as the complete truth, the following points should be used as a guideline perhaps as a Quick Reference Card.

- Is this document adding new value to other written documents related to the same functionality/processes?
- What is the level of knowledge about these documents to others?
- Is a reading instruction needed for those documents?
- Are the requirements discussed with the customer how to write them down in the document?
- Did previous changes on similar functionality lead to discussions/questions/meetings and how can this be avoided in this document?

Document Structure
- Did the writer have to adapt the content to make it fit the template?
- When did this happen: in the beginning of writing the document or later on?
- Where did this happen in the document?
- Did the writer struggle during writing the document to define functionality on the proper place of the document?
- When did this happen: in the beginning of writing the document or later on?
- Where did this happen in the document?
- How did the writer managed to use the structure making the content fit?

Usage of words
- How are used examples supporting the explicitly defined situations?
- How is it made clear that used examples are related to defined situations in other documents?
- If a translation had to be made from one language to another language are the key words of requirements used in the correct context?
- In which way are variables/conditions from the business rules made explicit and was this needed as results of common knowledge or specific knowledge?
- When and were did the writer struggled finding the proper word to describe the functionality and matching the requirement?

Explanation of functionality
- How did the writer made the relation between the functionality and business rules?
- How explained the writer unusual situations of defined functionality?
- What must be done to translate the written functionality in an image like process flow, time axes, etc?
- When and where are other chapters or paragraphs needed to support the explanation of the functionality?

- Is there enough information in the document the writer can hand this document over to a colleague and he/she is able to explain it to the developer?
- Is the writer able to explain the relation between business rules and the functionality based on the information in the document?
- What arguments can be thought of to support the size of the document with respect to the impact and value of the requirement?

As often, more questions can be asked/defined. In my opinion the questions mentioned above can be used to question your document. I tried to write them in a way you are triggered to ask more questions. I believe when you are not triggered to ask more questions you might spend more time on your document and with your colleagues talking about the functionality.


  1. Hi Jeroen,

    I was wondering if you would have an email address that I could reach you on?

    Kind regards,


  2. Hello Ina,
    I thought I had my adress on this blog, somehow it was removed agian by me.
    you can contact me at: jeroen.rosink[at]
    You made me curious for which purpose