Software Documentation Code Documentation User 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. This documentation is usually embedded within the source code itself so it is readily accessible to anyone who may be traversing it.

This writing can be highly technical and is mainly used to define and explain the API's, data structures and algorithms. For example, to spell out that the variable m_name refers to the first and last name of a person. 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, javadoc , ROBODoc, or TwinText 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 (for example, 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. This makes is much easier to keep to documentation up-to-date.

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 documents nightly). Some would characterize this as a pro rather than a con.

2 User Documentation

Unlike code documents, user documents are usually 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 documents and user documents could be effectively equivalent and are worth conjoining, but for a general application this is not often true. On the other hand, the Lisp machineLisp machines were general purpose computers designed (often with hardware support) to efficiently run Lisp as their main language. In a sense, they were the first commercial single-user workstations. History Artificial intelligence computer programs of t grew out of a tradition in which every piece of code had an attached documentation string. In combination with strong search capabilities (based on a UnixUNIX (or Unix is a portable, multi-task and multi-user computer operating system originally developed by a group of AT&T Bell Labs employees including Ken Thompson, Dennis Ritchie and Douglas McIlroy. Unices The term Unices includes Unix and Unix-like ope-like apropos command), and online sources, Lispm users could look up documentation and paste the associated function directly into their own code. This level of ease of use is unheard of in putatively more modern systems.

In the usual case, the user documentation describes each feature of the program, and the various steps required to invoke it. A good user document can also go as far as to provide thorough troubleshoot ing 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 indexSee Also Index, Washington, United States. An index (pl. indices, sometimes indexes) is a pointer (literally note that the index finger is the one which points, or indicates that takes you to information. Traditionally indices are found at the back of boo. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do and should be free from undocumented featureUndocumented features are frequently found in software releases. They are often elements of the software not intended for use by everyday end users, but left available for use by software support and knowledgeable end users who have learned of them througs.

There are three broad ways in which user documentation can be organized. A tutorialIf you are looking for a tutorial about editing Wikipedia, see Tutorial. In academic parlance, a tutorial is a small class of one, or only a few, students, in which the tutor (a professor or other academic staff member) gives individual attention to the s approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks. A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. The final type of organizing principle is one in which commands or tasks are simply listed alphabetically, often via cross-referenced indices. This latter approach is of the greatest use to advanced users who know exactly what sort of information they are looking for. A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two.

It is common to limit provided software documentation for personal computers to online help files that give only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the manufacturer.

3 Design Documentation

Unlike code or user documentation, design documents 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 documents or user documents, but it is important for design.

4 Architecture Documentation

This is a special breed of design documents. In a way, architecture documents are third derivative from the code (design documents being second derivative, and code documents being first). Very little in the architecture documents is specific to the code itself. These documents 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 existence 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.

5 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 obtuse 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.

6 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:

To excite the potential user about the product and instill in them a desire for becoming more involved with it.
To inform them about what exactly the product does, so that their expectations are in line with what they will be receiving.
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.

It is not uncommon for the software box and other marketing materials to give a clearer picture of the uses and capacities of the program than anything else provided by the manufacturer.

Home > Software documentation

1 Code Documentation