Types of documentation and their importance
Documenting the System
In one sense, every information systems development project is unique and will generate its own unique documentation. In another sense, though, system development projects are probably more alike than they are different.
Each project shares a similar systems development life cycle, which dictates that certain activities be undertaken and that each of those activities be documented. Specific documentation will vary depending on the life cycle you are following, and the format and content of the documentation may be mandated by the organization you work for. Start developing documentation elements early, as the information needed is captured.
Types of documentation in system:
We can simplify the situation by dividing the types of documentation into two basic types,
- system documentation and
- user documentation.
records detailed information about a system’s design specifications, its internal workings, and its functionality. System documentation can be further divided into internal and external documentation.
is part of the program source code or is generated at compile time. External documentation includes the outcome of all of the structured diagramming techniques, such as data-flow and entity-relationship diagrams.
is written or other visual information about how an application system works and how to use it. Although not part of the code itself, external documentation can provide useful information to the primary users of system documentation—maintenance programmers.
For example, data-flow diagrams provide a good overview of a system’s structure. In the past, external documentation was typically discarded after implementation, primarily because it was considered too costly to keep up to date but today’s integrated development environment makes it possible to maintain and update external documentation as long as desired.
Whereas system documentation is intended primarily for maintenance programmers, user documentation is intended mainly for users. An organization should have definitive standards on system documentation.
These standards may include the outline for the project dictionary and specific pieces of documentation within it. Standards for user documentation are not as explicit
User documentation consists of written or other visual information about an application system, how it works, and how to use it. An excerpt of online user documentation for Microsoft Visio appears in Figure 10-7. The documentation lists the item necessary to perform the task the user inquired about. The user controls how much of the help is shown.
Figure 10-7 represents the content of a reference guide, just one type of user documentation. Other types of user documentation include a quick reference guide, user’s guide, release description, system administrator’s guide, and acceptance sign-off. Most online reference guides allow you to search by topic area or by typing in the first few letters of your keyword. Reference guides are greatfor specific information (as in Figure 10-7) but are not as good for the broader picture of how to perform all the steps required for a given task. The quick reference guide provides essential information about operating a system in a short, concise format.
Where computer resources are shared and many users perform similar tasks on the same machines (as with airline reservation or mail-order-catalog clerks), quick reference guides are often printed on index cards or as small books and mounted on or near the computer terminal. The purpose of a reference guide is to provide information on how users can use computer systems to perform specific tasks.
The information in a user’s guide is typically ordered by how often tasks are performed and how complex they are. Increasingly, software vendors are using Web sites to provide additional user-guide content.
Figure 10-8 shows the Microsoft Visio help page. Web-based documentation allows the vendor to provide more up-to-date reference material without issuing new software CDs. Because most software is reissued as new features are added, a release description contains information about a new system release, including a list of complete documentation for the new release, features and enhancements, known problems and how they have been dealt with in the new release, and information about installation.
A system administrator’s guide is intended primarily for a particular type of user—those who will install and administer a new system—and contains information about the network on which the system will run, software interfaces for peripherals such as printers, troubleshooting, and setting up user accounts. Finally, the acceptance sign-off allows users to test for proper system installation and then signify their acceptance of the new system and its documentation with their signatures.
Importance of documentation for the developer
Each function in a piece of software solves a specific problem. Before you try to solve any problem, you should have a good understanding of exactly what the problem is. It makes no sense just to start writing and then, afterwards, look at what you have come up with to see whether it solves any useful problem!
Inexperienced computer programmers imagine that they can keep all problem descriptions in their heads. Experience has shown that they can't. Three issues come up.
When writing a function definition without written documentation, you only have a rough idea of what it is supposed to do. While you write, the idea morphs in your head. A simple interruption can cause the idea to lose what focus it has. You start thinking about the program as a whole instead of thinking of just the function that you are working on, and the function starts to take on responsibilities that it should have nothing to do with.
Suppose that you test the function and find that it does not work. So you need to fix it. But during the process of fixing it, you have nothing but your memory telling you want the function is supposedto do. It is difficult to keep that in your head along with the details of how the function is supposed to work, and the process of fixing a function definition takes the function further away from its original intent.
Later, when you need to use that function, you have forgotten just what it does. Unwilling to reverse-engineer it, you make a guess based on what you remember. You often forget important details, and your software does not work because of it. You are faced with laborious debugging to find out what is going on.
Importance of documentation for the maintainer
You might have heard of "self-documenting code". The idea is for functions to be written in a readable form so that, to find out what a function does, you just read the function's definition. For very small pieces of software that can be achieved. But imagine a larger piece of software, say with about 1000 functions. Such software is built up function upon function; one function typically uses a few others that are defined in the same collection of 1000 functions, with the exception of the bottom-level functions that only use the library.
Suppose that the software has no internal documentation, and relies on "self-documenting code". Now you want to understand what a particular function does. But it uses 3 other undocumented functions, so you need to understand what they do first. Each of those uses 2 undocumented functions, so you must read their definitions too. It goes on and on. You find yourself reading thousands of lines of code to understand a single function whose body is only ten lines long.
The only way that anyone can work with undocumented software is to reverse-engineer the whole thing and add documentation that should have been written by the developer. Most of the time, that is too difficult. Undocumented software is often just thrown away as unmaintainable.