Wednesday, October 31, 2007

Documentation:

Software documentation or source code documentation is written text that accompanies computer software. It either explains how it operates or how to use it, or may mean different things to people in different roles.
Documentation is an important part of software engineering. Types of documentation include:
• Architecture/Design - Overview of software. Includes, relations to an environment and construction principles to be used in design of software components.
• Technical - Documentation of code, algorithms, interfaces, and APIs.
• End User - Manuals for the end-user, system administrators and support staff.
• Marketing - Product briefs and promotional collateral.
Architecture/Design Documentation:
Architecture documentation 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). 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.
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.
End User Documentation:
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.
Marketing Documentation:
For many applications it is necessary to have some promotional materials to encourage casual observers to spend more time learning about the product. One good marketing technique is to provide clear and memorable catch phrases that exemplify the point we wish to convey, and also emphasize the interoperability of the program with anything else provided by the manufacturer.

No comments: