Artistic Communication

Technical documentation is one of the least appreciated aspects of software development -- not the written words themselves, but the process of creating them is deeply undervalued. Effective technical documentation is like a Hail Mary pass from the developer in the present to the developer in the future with the intervening crosswinds of bug fixes and changes to the business rules complicating the reception.

The developer is usually the best person to author technical documentation: he understands the implicit trail of bread crumbs that he has already left in the code for somebody else to follow. If he was involved in the project from the start then he can also relate to the politics and priorities that the team faced from the design and implementation stages.

A technical document should begin with a Background section that describes the rationale behind the project and the challenges that sufaced during design and implementation. This should alert future developers to any political or technical potholes that they should avoid.

Next an Architecture section should briefly describe data flows, timing constraints, and security layout. Next some Entity Relationship diagrams: not the whole thing but just the key tables and their relationships. Then a high-level UML and quick use-case diagram, focusing on how employee responsibilities overlap with components of the system. Finally, reference the design specifications that can, at this point, direct the developer to the whole ball of wax.

Good technical documentation isn't extraordinarily deep or complicated provided that you focus on its main intent. Sure you understand the system (because you created it), but standing at the other end of the football field a future developer can easily get buried in minutiae. Wipe away those confounding crosswinds and throw that future developer a touchdown.