LINFO

Documentation Definition

Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use.

Benefits of Good Documentation

Good documentation can serve several very important functions with regard to computer software (i.e., operating systems, application programs, library functions, etc.). One is that it can make it easier to use and thereby save users time, frustration and money.

It can also be useful for the developers and vendors of software because it can reduce the need for time-consuming and costly support (e.g., phone calls, e-mails and on-site visits). Moreover, it can enhance the perceived quality of the product and thereby lead to increased sales and profits for proprietary (i.e., commercial) software.

Good documentation also facilitates the improving, extending and updating of software. Because programs can be extremely complex, their developers often forget what they were doing or thinking when they created them, particularly after the passage of long periods of time. Moreover, it is frequently the case that some or all of the original writers of a program are no longer available, thus making it even more difficult to understand the original software in order to improve, extend or update it. It is often said that the largest cost of software is not creating it, but rather maintaining it (i.e., correcting errors and updating it); good documentation can help reduce this cost. Good documentation can also help users make useful suggestions for improving the software.

Furthermore, in addition to the existence of good documentation, the actual process of creating the documentation itself can be useful if done concurrently with the development of software. This is because it can help uncover problems in the software at various stages of its development and thus provide feedback to the developers for correcting and improving it.

Forms of Documentation

Documentation can mean different things in different contexts. For example, there are major differences in documentation for a legal case, a scientific study, an art collection and computer software. And documentation can take many different forms even in a single context.

In the case of computer software these forms commonly include printed materials (e.g., quick start cards, manuals and books), computer-readable text (e.g., plain text files, hyperlinked help systems and web pages), audio and video (e.g., computer-based video files, video tapes and telephone-based question and answer service) and built-in documentation (e.g., built-in manuals, tooltips and even intuitive design).

A tooltip is a small box containing text briefly identifying or explanatory text that appears adjacent to an object (e.g., buttons in a toolbar) in a graphical user interface (GUI) when a pointer or other cursor controlled by a mouse passes over that object.

Documentation can be either external to a system or built into it. Some operating systems, such as Unix-like systems, and some application programs provide large amounts of both built-in and external documentation.

The traditional main form of documentation for users of Unix-like operating systems is the built-in manuals that are accessed via the man and info commands. This extensive documentation is particularly useful for obtaining information about the hundreds of small command line (i.e., all-text mode) programs that are standard parts of such systems. The main complaint about it is that it can seem cryptic to newcomers; however, it is common for users to not only become used to it but also to come to appreciate its excellent combination of terseness and thoroughness.

Documentation of Source Code

One of the most important forms of documentation for computer software is one that ordinary users rarely, if ever, see. It is the comments that are included in the source code of programs. Source code is the version of software (usually an application program or an operating system) as it is originally written (i.e., typed into a computer) by a human in plain text (i.e., human readable alphanumeric characters) in a programming language.

Comments are separated from the source code by special markers and do not affect its operation. They are statements by programmers explaining their code to other programmers who may work on the same programs and to remind themselves of what they did or what remains to be done. The comments ideally include the reasons that each section of code is written a particular way and what it is intended to do.

Another technique that can help document source code is what is sometimes referred to as self-documenting code. This strives to make the code itself as clear to humans as possible without adversely affecting its functioning in order to minimize the need for comments. A major way in which this is accomplished is by using descriptive rather than arbitrary names for the various components of the code (e.g., variables, functions, objects and modules). For example, a variable in a program used by railroads could be named tons_Of_Freight_Carried_Per_Month rather than xfc5_s.

Bad Documentation

Unfortunately, the documentation for software (as well as for many other products) is often far from ideal. The problems are diverse, and they include incompleteness, lack of clarity, inaccuracy, obsolescence, difficulty of access and lack of availability in local languages. This is the result of several factors, including the high cost of creating and maintaining good documentation, the fact that programmers usually do not like to write documentation and often are not good at it, the difficulty in finding people who are both skilled at writing and have a good understanding of the technology, the vast amount of material that needs to be documented and the large number of human languages in use.

Although poor documentation is usually not intentional, there are some situations in which it could benefit a software developer or vendor, particularly if it has some degree of monopoly (i.e., the sole producer or supplier) for a particular class of software, to produce inferior documentation that looks good superficially. One is where it is desired to keep certain aspects of the software secret, for example, undisclosed techniques for developing applications for the software that might only be shared with a few favored developers. Another is to facilitate having a lucrative business of selling expensive service contracts and consulting services for the software.

Open source software (i.e., software for which the source code is freely available) is ideally suited for high quality documentation. This is because by its very nature there are no secrets and there are no incentives to purposely supply low quality or incomplete documentation (other than cost or laziness). Thus everything can be documented, and all documentation can be easily reviewed by numerous and diverse people, just as the source code is.

There is, in fact, a great amount and variety of documentation for Linux and other free software, which is software for which the source code is available to anyone at no cost and for any desired purpose. It is available in various forms and locations, including built into the operating system, on the Internet and in books. Unfortunately, as is the case with proprietary software, it is far from complete. However, the reason is largely the massive and rapidly growing (due to the very large number of programs being developed) amount of material that needs to be documented.

Documentation and Information

There is a major difference between documentation and information. Documentation is merely one type of information, and information is much more inclusive than documentation. Whereas the focus of documentation is on how to install, use or repair a product, information can be not only about a product, but about any topic. And when it is about a product, information is not necessarily just about how to install, use and repair it. Rather, it can also cover every aspect of the product, including its historical, business, economic, scientific, political, philosophical, sociological and environmental aspects.

Both documentation and information can have important roles. For many products, all the information that is necessary for most people is good documentation. But for other products, it can be desirable to have a broader range of information. The latter is particularly important for creative people, such as developers who will be improving or extending a product or thinking about developing new products.