The Writing Problem
Let's face it: the majority of software developers do not have well developed writing skills.
In response to the documentation crisis which cursed so many long term projects with normal rates of staff turnover, many organizations turned to highly formalized standards. In the eighties the DOD-2167A standard was all the rage. It was a huge set of standards, aimed at massive projects with strict auditing requirements, and overkill for most small and medium scale projects. Too many organizations duly mandated the creation of the requisite “analysis”, “preliminary design”, “final design”, etc. series of documents. As often as not, a lot of time was spent generating a lot of paper, but with no corresponding improvement in the quality or comprehensibility of the code.
I saw this at work in a company where the programmers, unable to comprehend the intent and expected content of mandated documents with standardized formats, took to cutting and pasting material from one document to another to satisfy mandated formats.
I have created a lot of software design documentation, and on no two projects did I use the identical format, organization, or level of detail. I’m guided by what I call the “drop dead principal”. Simply put, if the key senior technical staff of the project get hit by a bus tomorrow, what set of documents would provide their successors with a clear, accurate view of the architecture and implementation of a complex body of code? Following that principle, and possessing the requisite writing skill, is the key to good software documentation, rather than blindly adhering to an arbitrarily imposed set of standards.
Fundamental to good documentation practice is avoidance of duplication. This is a common problem when a "cascading" set of documents (think "analysis, "preliminary design", "detailed design", etc.) is created. As more details are fleshed out, assumptions reflected in previous documents inevitably need to be reconsidered. Usually, the original documents are not modified to reflect the new understanding, yet still form part of the formal documentation set. Invariable, a member of the development team, a marketing person, or the client ends up referring to obsolete information. The ensuing contradictions and misunderstandings can have serious consequences.
Minimalism is the vital concept here. Each document must have a clearly defined and understood purpose, and contain only the information required to satisfy that purpose. For many typical small systems the set might include only a user manual (or online help system), and a detailed architecture document. Both are successively revised - rather than replaced with new documents - to reflect changed requirements and greater levels of detail as design and implementation decisions are made. An outline will often serve as the first draft.