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.

System 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.

Internal 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.

User documentation

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

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.

Types of documentation and their importance

   Types of documentation and their importance


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.

  1. 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.

  2. 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.

  3. 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.

Frequently Asked Questions

Ans: Systems Planning and Selection : The first phase of the SDLC, in which an organization’s total information system needs are analyzed and arranged, and in which a potential information systems project is identified.Systems Analysis : Phase of the SDLC in which the current system is studied and alternative replacement systems are proposed. view more..
Ans: Systems development methodology: A standard process followed in an organization to conduct all the steps necessary to analyze,design, implement, and maintaininformation systems. | Systems development life cycle (SDLC): The series of steps used to mark the phases of development for an information system. view more..
Ans: Change Agent: The analyst may be viewed as an agent of change. A candidate system is designed to introduce change and reorientation in how the user organization handles information or makes decisions. Then, it is important that the user accepts change. view more..
Ans: System documentation: Detailed information about a system’s design specifications, its internal workings, and its functionality. Internal documentation: System documentation that is part of the program source code or is generated at compile time. view more..
Ans: Management should not be lenient on part of documentation, management should never say like  “ as time running short , so just create the system and make the documentation later”. Phase should not be considered complete until documentation is done. Coding should not be considered done unless its has required comment lines. view more..
Ans: There are various techniques to gather data and facts of system. some of them re as follows : Record view and Background reading Interviews  Questionnaires Group communication Presentation Site visiting Observation view more..
Ans: Feasibility studies are almost always conducted where large sums are at stake. Also called feasibility analysis. A feasibility study is conducted in order to determine the success and minimize the risks related to the project. When it becomes certain that the specific project could be carried out profitably view more..
Ans: It is a final report of the feasibility study about the findings and conclusion of the study. it should be possible to review report and take decision on the project based on it view more..
Ans: System selection means selecting the various hardware, software, and services that are needed for implanting the system. Before the system selection can be done, it is necessary to know the capabilities of required proposed system view more..
Ans: Costs fall into two categories. There are cost associated with developing the systems and there are costs associated with a operating a system. view more..
Ans: Quantitative measure of degree to which a system, component or process possesses a given attribute For ex. No. of errors found per person hours expended Cost and Effort Estimation : Boehm’s COCOMO model, Putnam’s SLIM Model & Albrecht’s function model. view more..
Ans: There are three such classes: Process are collection of software related activities. Products are any artifacts, deliverables or documents that result from a process activity view more..
Ans: A direct measure is obtained by applying measurement rules directly to the phenomenon of interest.For example, by using the specified counting rules, a software program’s “Line of Code” can be measured directly. and sofware reliabity is .... view more..
Ans: What Is Information Systems Analysis and Design? Information systems analysis and design is a method used by companies ranging from IBM to PepsiCo to Sony to create and maintain information systems that perform basic business functions such as keeping track of customer names and addresses, processing orders, and paying employees. The main goal of systems analysis and design is to improve organizational systems, typically through applying software that can help employees accomplish key business tasks more easily and efficiently. As a systems analyst, you will be at the center of developing this software. view more..
Ans: concurrency of components, lack of a global clock and independent failures of components and the ability to work well when the load or the number of users increases – failure handling, concurrency of components, transparency and providing quality of service view more..
Ans: the wide range of applications in use today, from relatively localized systems (as found, for example, in a car or aircraft) to globalscale systems involving millions of nodes, from data-centric services to processorintensive tasks, from systems built from very small and relatively primitive sensors to those incorporating powerful computational elements, from embedded systems to ones that support a sophisticated interactive user experience, and so on. view more..
Ans: The task of a web search engine is to index the entire contents of the World Wide Web, encompassing a wide range of information styles including web pages, multimedia sources and (scanned) books view more..
Ans: The growth of the World Wide Web as a repository of information and knowledge; the development of web search engines such as Google and Yahoo to search this vast repository view more..

Rating - 4/5