SYSTEM DOCUMENTATION THEORY

16.2.2.10.T0 Specific Objectives

112 By the end of this topic, the trainee should be able to:

a) explain the meaning of system documentation

b) explain the need for system documentation

c) describe the types of system documentation

CONTENT

Meaning of system documentation

In computer hardware and software product development, documentation refers to: The
information that describes the product to its users. It consists of the product technical
manuals. The term is also sometimes used to mean the source information about the product
contained in design documents, detailed code comments, etc.

The term is derived from the idea that engineers and programmers "document" their products in
formal writing. The earliest computer users were sometimes simply handed the engineers' or
programmers' "documentation." As the product audience grew, it became necessary to add
 professional technical writers and editors to the process. In this task-oriented view, product
information can be divided into and sometimes physically organized into these task categories:
evaluating, planning for, setting up or installing, customizing, administering, using, and
maintaining the product. Documentation is now often built directly into the product as part of the
user interface and in help pages.

Functional specification

Definition

A functional specification is a formal document used to describe in detail for software developers
a product's intended capabilities, appearance, and interactions with users.

The functional specification is a kind of guideline and continuing reference point as the
developers write the programming code. Typically, the functional specification for an application
program with a series of interactive windows and dialogs with a user would show the visual
appearance of the user interface and describe each of the possible user input actions and the
program response actions. A functional specification may also contain formal descriptions of user
tasks, dependencies on other products, and usability criteria.

For a sense of where the functional specification fits into the development process, here are a
typical series of steps in developing a software product:

 Requirements. This is a formal statement of what the product planners informed by their
knowledge of the marketplace and specific input from existing or potential customers believe is
needed for a new product or a new version of an existing product. Requirements are usually
expressed in terms of narrative statements and in a relatively general way.
 Objectives. Objectives are written by product designers in response to the Requirements. They
describe in a more specific way what the product will look like. Objectives may describe
architectures, protocols, and standards to which the product will conform. Measurable objectives
are those that set some criteria by which the end product can be judged. Objectives must
recognize time and resource constraints.
 Functional specification. The functional specification (usually functional spec or just spec for
short) is the formal response to the objectives. It describes all external user and programming
interfaces that the product must support.
 Design change requests. Throughout the development process, as the need for change to the
functional specification is recognized, a formal change is described in a design change request.
 Logic specification. The logic specification describes internal interfaces and is for use only by
the developers, testers, and, later, to some extent, the programmers that service the product and
provide code fixes to the field.
 User documentation. In general, all of the preceding documents (except the logic specification)
are used as source material for the technical manuals and online information (such as help pages)
that are prepared for the product's users.
 Test plan. Most development groups have a formal test plan that describes test cases that will
exercise the programming that is written. Testing is done at the module (or unit) level, at the
component level, and at the system level in context with other products. This can be thought of as
alpha testing. The plan may also allow for beta test. Some companies provide an early version of
the product to a selected group of customers for testing in a "real world" situation.
 The final product. Ideally, the final product is a complete implementation of the functional
specification and design change requests, some of which may result from formal testing and beta
testing.

The cycle is then repeated for the next version of the product, beginning with a new Requirements
statement, which ideally uses feedback from customers about the current product to determine
what customers need or want next.

Most software makers adhere to a formal development process similar to the one described above.

Need for system documentation

It helps to provide the clear description of the work done so far. It is essential that the documents
prepared must be updated on regular basis this will help to trace the progress of work easily. With
appropriate and good documentation, it is very easy to understand the how aspects of the system
will work for the company where the system is to installed. It also help to understand the type of
data w h i c h will be inputted in the system and how the output can be
produced.

After the system is installed, and if in case the system is not working properly it will be very easy
for the administrator to understand the flow of data in the system with documentation which will
help him/ her to correct the flaws and get the system working in no time.

Uses of Documentation

 It facilitates effective communication regarding the system between the technical and the
non-technical users.
 It is very useful in training new users. With a Good documentation new users can easily get
acquainted with the flow of the systems.
 Documentation also helps the users to solve problems like trouble shooting even a non-technical
user can fix the problems.
 It plays a significant role in evaluation process.
 It not only helps to exercise a better control over the internal working of the firm, but it also
external as well especially during audit.
 Documentations can help the manager to take better financial decisions of the organization.

The Value of Documentation

Documentation is valuable as reference and standardization material and because it creates value
for organizations and products:
 Good documentation tends to reduce the volume of support requests and erroneous bug/issue
reporting. Additionally, good comprehensive documentation makes responding to the remaining
support requests easier.
 Good documentation gets knowledge out of people‘s heads and into a shared format. This
increases reliability, because it reduces a dependence on people‘s memories and notes, which may
not always be accessible, or may be inconsistent.
 In absence of a specification, documentation can help define and regulate the user experience as
development proceeds.
 Without documentation users may be unaware of features and behaviors, which reduces their
value. If users never learn about or take advantage of new features and functionality, then
development resources are essentially wasted.

This doesn‘t mean you should write documentation in situations where organizing a system or
environment is more practical and efficient, or that standardizing a process with a script or
program doesn‘t have it‘s place. However, for complex problems where users interact with your
interfaces or processes, documentation is often the answer. Take pride in documentation, treat it
seriously, and the return will be great.

Types of system documentation

Sommerville describes two main categories of software documentations; process and product
documents.

Process:
documentations are used to manage the development process for example planning, scheduling
and cost tracking, standards among others.

Product documentations:
Describe the main deliverable (software product) and some of the documents in this category
form part of deliverables. These include;
 Requirements Specification,
 Design documents,
 Commented Source Code,
 Test Plans including test cases,
 Validation and Verification plan and results

Application and benefits of documentation

The role of documentation in a software engineering environment is to communicate
information to its audience and instil knowledge of the system it describes.
 System documentation plays another role namely software maintenance, and
 Identified several benefits of documentation. These include:
 easier reuse of old designs,
 better communication about requirements,
 more useful design reviews,
 easier integration of separately written modules,
 more effective code inspection,
 more effective testing, and
 more efficient corrections and improvements.
Researchers and practitioners also have looked at the uses of software
documentation and just to compile a few, notes that documentation helps
at software development, keeps software- quality at high levels and makes
it easy to transfer projects.
Documentation can also be used for:
 learning a software system,
 testing a software system,
 working with a new software system,
 solving problems when other developers are unavailable to answer
questions,
 looking for big-picture information about a software system
 maintaining a software system
 answering questions about a system for management or customers,
 looking for in-depth information about a software system, and
 facilitates effective communication regarding the system between the
technical and the non- technical users,
 training new users,
 solve problems like trouble shooting, evaluation process, and
quantify the financial
ramifications/footprint of the system.