Software documentation

When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of it. This is generically called "documentation", but it is more proper to distinguish between the various forms:

Code Documentation - This is what I think many programmers think of with the word 'documentation'. This writing is highly technical and is mainly used to define and explain the API's and data structures. E.g., to spell out that the variable "m_name" refers to the first and last name of a person. Often, one will inline this kind of documentation within the source code, thereby allowing a tool such as Doxygen to auto-gen the code doc's. It is important for the code docs to be thorough, but not so verbose that it becomes difficult to maintain them. Code docs are often organized into a "reference guide" style, allowing a programmer to quickly look up an arbitrary function or class.

Programmers really like the idea of auto-generating documentation for various reasons. For example, because it is extracted from the source code itself (e.g., through comments), the programmer can write it while referring to his code, and can use the same tools he used to create the source code, to make the documentation.

Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the docs nightly.) Some would characterize this as a pro rather than a con.  ;-)

User Documentation - unlike code docs, user docs are far divorced from the source code of the program, and instead simply describe how it is used. (In the case of a software library, the code docs and user docs could be effectively equivalent and are worth conjoining, but for a general application this is not true.) The user docs would describe each feature of the program, and the various steps required to invoke it. A good user document would also go as far as to provide thorough troubleshooting assistance. It is very important for user docs to not be confusing, and for them to be up to date. User docs need not be organized in any particular way, but it is very important for them to have a thorough index. Consistency and simplicity are also very valuable.

Design Documentation - Unlike code or user documentation, design docs tend to take a much more broad view. Rather than describe how things are used, this type of documentation focuses more on the 'why'. For example, in a design document, a programmer would explain the rationale behind organizing a data structure in a particular way, or would list the member functions of a particular object and how to add new ones to the code. It explains the reasons why a given class is constructed in a particular way, points out patterns, and even goes as far as to outline ideas for ways it could be done better, or plans for how to improve it later on. None of this is appropriate for code docs or user docs, but it *is* important for design.

Architecture Documentation - This is a special breed of design docs. In a way, architecture docs are third derivative from the code (design docs being second derivative, and code docs being first.) Very little in the arch docs is specific to the code itself. These docs do not describe how to program a particular routine, or even why that particular routine exists in the form that it does, but instead merely lays out the general requirements that would motivate the existance of such a routine. A good architecture document is short on details but thick on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents.

Trade Study Documentation - Another breed of design docs is the comparison document. This would often take the form of a "whitepaper". It focuses on one specific aspect of the system and suggests alternate approaches. It could be at the user interface, code, design, or even architectural level. It will outline what the "IS" situation is, and describe one or more alternatives, and enumerate the pros and cons of each. A good trade study document is heavy on research, expresses its idea clearly (without relying heavily on obtuese jargon to dazzle the reader), and most importantly is impartial. It should honestly and clearly explain the costs of whatever solution it offers as best. The objective of a trade study is to divine the best solution, rather than to push a particular point of view. It is perfectly acceptable to make no conclusion, or to conclude that none of the alternatives are sufficiently better than the baseline to warrant a change. It should be approached as a scientific endeavor, not as a marketing technique.

Marketing Documentation - On the flip side of trade study docs, for many applications it is necessary to have some promotional materials to encourage casual observers to spend more time learning about the product. This form of documentation has three purposes: First, to excite the potential user about the product and instill in them a desire for becoming more involved with it. Second, to inform them about what exactly the product does, so that their expectations are in line with what they will be receiving. And third, to explain the position of this product with respect to other alternatives. One good marketing technique is to provide clear and memorable 'catch phrases' that exemplify the point we wish to convey, and also emphesizes the _feelings_ the product conveys in addition to the cold facts about it. Good marketing documentation builds a strong loyalty from the user for the product.

-- BryceHarrington