Documentation is probably one of the most hated subjects for most of the developers. The biggest reason is it is often difficult and tedious to be articulate in specifying what to do or what has been done. I have mentioned earlier why documentation is necessary for the user, in one form or another. A lot of professionals argue against this by saying that the software should be intuitive and easy for the user to not require documentation. However, it is also true that the ROI from software is out of using it the right way. This might involve not only the software operations but using software to be part of certain business process(es). And the documentation should talk about this.
Luke Wroblewski talks about documentation for project and product management. Documentation is required to record the rationale behind decisions. Decisions are hardly straightforward, they involve so many parameters that more often than not compromises happen, tradeoffs happen. The reasons and arguments behind them should be documented so that they can either work as justifications or wisdom for future decisions.
However, lost in this fast paced, quickly dated documentation environment is the rationale behind decision-making. What limitations required us to make certain trade-offs? Where did we opt for business goals over user needs or vice versa? When did we cut corners to meet specific timelines? These data points often need to be referenced as a product progresses forward but due to a lack of documentation longevity, they unfortunately tend to get lost.
Well said!
November 24th, 2006 at 11:59 pm
User documentation and developer documentation should differ significantly. Development documentation should be written in the event the developer is ‘hit by a truck’ and someone must immediately assume the responsibility for troubleshooting and enhancing the application.
User documentation, however, should provide the user with how the application can be utilized to solve the problem it was developed for. Too many times, application documentation is written as a roadmap to navigate the software rather than how to solve the actual problem.
November 25th, 2006 at 7:50 am
Completely agree with you Doug that user documentation and developer documentation target different people and should be significantly different in their composition and even the language. Developer documentation is useful in all cases as they record the decisions along with the reasons behind them.
March 10th, 2008 at 5:25 pm
[...] is not evil. I document to record rationale behind certain decisions or to document the problem that the code solves. There might be cases where you are building an API [...]
June 16th, 2009 at 9:08 am
[...] In-line comments can be effectively used for things that cannot be conveyed by code at times – the rationale behind design decisions and the problem the code is trying to [...]