Skip to main content

On the writing of adequate technical documentation

Posted by johnsmart on May 24, 2007 at 4:25 PM PDT

Some open source projects have excellent documentation (Spring and Hibernate come to mind). Some have none at all. Others are somewhere between the two extremes.

How much do you really need for your project (enterprise or open source)? What is the audience of your technical documentation? Is it an online community or hundreds or thousands of developers, or is it for the developers who will be in charge of maintaining your product?
IMHO, this is an important thing to consider when considering the trade-offs involved in writing technical documentation. Writing technical documentation is an honorably task, but when you write (and maintain) documentation, you aren't coding, testing, or contributing in some other way to the working product. So there is always a trade-off involved.

For open source projects, good quality documentation is obviously a must. However, for internal projects, I suspect that you can get away with much less manual technical documentation than you might think. This might be a slightly heretical view, but it's probably my Project Management training, mixed with a good dose of Agile influence, coming through. What is the cost-benefit of your documentation? How will it really contribute to getting the product delivered, or to helping future developers get their heads around a product? Do you really need a 100 page document describing the solution architecture? Or would a vision statement, guidelines and examples suffice?

Documents written by people will usually be easier to understand, more readable, and more presentable. But if they are too technical or detailed, they will be difficult to keep up to date. If they are too long, no one will read them.

Tools like Javadoc, SchemaSpy and DOxygen, on the other hand, produce decent, up to date, accurate, and reasonably usable online documentation, including (for the latter two) graphical database models, class diagrams and simple collaboration diagrams. With a few well-placed comments, and combined with a few strategic vision documents, this sort of automatically-generated documentation might be just enough to help a new developer understand the architecture of your product.

Related Topics >>