Over the past two days I spent about 8 hours writing documentation.
Was the documentation worth it? Will anyone ever read it? If they do, will it help? When is documentation done? Have we written too much? To little? Have we answered the questions that will be in the reader's mind?
That last question suggests that pair-documenting might be an effective approach. Here is how I see it proceeding.
- The Expert : this person either wrote the code or is very familiar with it.
- The Scribe : this person is not very familiar with the code but knows the underlying framework and/or language.
The Scribe is at the keyboard reading the code, trying to understand it, and asking questions of The Expert. Whenever The Expert answers a question, The Scribe writes down the answer as a comment to the block of code that triggered the question.
To me this seems like it would be much more worthwhile than having The Expert guess what comments will be helpful.
This would also work for long-form documentation of a complex system.