What are the best practices for technical reports

Question

How do you, as a programmer, think that a technical report on a software should be done, in a manner that can optimize the task of another programmer take it and start feeling confortable with the code as fast as can.

Answer 1

I'd say that a nice set of unit tests is probably better than a technical report.

Answer 2

Put a list of things that need to get done into a tracking system (Jira is you have the dough), giving as much outline as is necessary to get each task done. Good developers feel comfortable the quickest when they are in code.

Answer 3

Make sure to include a cover sheet on your report, especially if it's a TPS one.

Answer 4

I look at documentation on two levels: SourceCode documentation and Design Documentation

Source Code documentation is very useful if done in the javadoc or equivalent style. You can autogenerate reference documentation and some IDEs can make good use of the info. Other than that, limit source code comments to why things are happening or on very tricky algorithms.

Design Documentation should encompass the big picture. Focus on how all the pieces fit together. Provide examples (use cases, etc.) on how things flow through the system. How various classes and subsystems interact will be invaluable in determining where to plugin new functionality.

The most important thing, though, is to document the system as it is today, not how it was a year ago, or how it was supposed to be. Otherwise, the docs will be worse than useless. I think you'll find this point sufficiently difficult to achieve that you need not worry about any other "best practices".