Answer Question by Updating Manual

Writing code, writing the manual, supporting the product, and testing the code all go hand-in-hand.  When I get a question on the product, it is an opportunity to improve the manual

Every question you get is an opportunity to improve the product or improve the manual.  For every question, I go through this list:

1. Could the product be improved?

Did the user run into a problem that could be avoided by improving the program?  Every problem is the result of no quite understanding how the program works.  Could we make the product run more like people expect, so they would not hit this problem?  This way you don’t need to write documentation at all — people use it naturally and without noticing any conflict.  This is not always possible because there are some thing that must be done a certain way and they are inherent to application domain.

2. Does the manual describe how to avoid the problem?

If you have to approach doing things a certain way, does the manual explain how to do it?  If this is just a gap of understanding of how the user is expected to use the product, then that should be clarified in the manual.  Then I will send the updated manual section to them, and ask them if that clarifies the situation.

3. If it is in the manual, is manual clear?

Is the manual difficult to read?  Or is the information buried in a place they would not expect it?  If problem, fix the manual and send it to them as the answer.

4. If clear in manual, is there something I don’t understand?

If no improvement to the manual seems obvious, then send the manual as it is, and ask the person whether the manual is sufficient.  It is possible that they just didn’t read the manual.  It is also possible that the manual is jargon laden, or there are people from a particular culture, and the manual just does not get to them.


By following this method on every question, we get a chance to either improve the product, or improve the manual or both — and this help to reduce the amount of support questions in the future.

This drives the manual to be optimized for support.  We fill int he answers that get the most questions first.  It is responsive, and it is Agile.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s