Technical Documentation


This is what most programmers mean when using the term software documentation. When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them.

Often, tools such as Doxygen, NDoc, javadoc, SandCastle, ROBODoc, POD , TwinText , or Universal Report can be used to auto-generate the code documents-that is, they extract the comments from the source code and create reference manuals in such forms as text or HTML files. Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.

Many programmers really like the idea of auto-generating documentation for various reasons. For example, because it is extracted from the source code itself, 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. This makes it much easier to keep the documentation up-to-date.

User Documentation

Unlike code documents, user documents are usually far more diverse with respect to the source code of the program, and instead simply describe how it is used.

In the case of a software library, the code documents and user documents could be effectively equivalent and are worth conjoining, but for a general application this is not often true. Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. A good user document can also go so far as to provide thorough troubleshooting assistance. It is very important for user documents to not be confusing, and for them to be up to date. User documents 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. User documentation is considered to constitute a contract specifying what the software will do.

There are three broad ways in which user documentation can be organized.

(a) Tutorial

A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks.

(b) Thematic

A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user.

(c) List or Reference

The final type of organizing principle is one in which commands or tasks are simply listed alphabetically or logically grouped, often via cross-referenced indexes. This latter approach is of greater use to advanced users who know exactly what sort of information they are looking for.

Leave a Reply

Your email address will not be published. Required fields are marked *