SYSTEM DOCUMENTATION
system documentation: The collection of documents that describes the requirements, capabilities,
limitations, design, operation, and maintenance of a system, such as a communications, computing, or
information processing system.
NEED FOR SYSTEM DOCUMENTATION
Features of Effective System Documentation:
Effective system documentation should possess the following characteristics:
1. It must be clearly stated in the language that is easily understood.
2. It should be possible to refer to other documents.
3. It should contain everything needed, so that those who are reading it carefully understand the
system.
4. It should be accessible to those for whom it is intended.
5. When the system gets modified it should be easy to update the documentation.
Purpose of System Documentation:
The formal system documentation fulfills the following objectives:
1. To provide the necessary information to develop training programme for operators and users.
2. To create a vehicle of information to provide evidence of progress in the development process
and to monitor the process.
3. To make conversion of a system from one machine to another machine easier.
4. To make system modification and implementation easier.
5. To narrow down the communication gaps among users, designers and management.
6. To provide a means to determine in advance what will occur and when.
Contents of System Documentation:
The report on the system design should contain the following elements:
1. An overview of the entire project describing the general purpose of the system with the
relevant information.
2. Documentation for every input and output used in the system. Each document should
accompany each design and explain the purpose and use of each form.
3. Documentation of every file of the system, creating and update sequences of the file should be
there.
4. System flowchart describing the series of steps used in the processing of data.
5. A financial analysis of the proposed and existing systems, providing present and future costs
with potential cost savings.
6. A description of the computer system and its peripheral equipment’s.
The Importance of Documentation in
Software Development
For a programmer reliable documentation is always a must. The presence of documentation
helps keep track of all aspects of an application and it improves on the quality of a software
product. Its main focuses are development, maintenance and knowledge transfer to other
developers. Successful documentation will make information easily accessible, provide a
limited number of user entry points, help new users learn quickly, simplify the product and help
cut support costs. Documentation is usually focused on the following components that make up
an application: server environments, business rules, databases/files, troubleshooting,
application installation and code deployment.
Server Environments
Detailed documentation about an application and its environments is always a must. This
information will help with setting up new environments for your application and it should
present the location and function of the systems that run your services. Things that should be
specified here are the application name/version, server name, IP, code directory, URL to the
application, operating system, user account information and a point of contact.
Business Rules
Business rules documentation help new additions to the team adapt faster to the working
habits of the company. It provides information on how the product works and why. Business
rules documentation can easily be supported with requirements documents if available. This will
speed up a developer's learning curve significantly. In addition to business rules, a help
document, FAQs, or user guide can help highlight the main points of an application for a
developer who needs context for the application they are supporting.
Database/Files
Database information is mandatory for porting, reverting, sharding, migrating and so on. It is
important to know the type of database, the server information, the version but most
importantly to have a data model diagram. Documentation of the database will make bringing
additions to the table, modifications to the structure and types, additions of indexes and keys
much more simpler and easier to control/debug. Also, if an application presents a file transfer
functionality, it is recommended to document which way the transfer is made, through which
protocol and datatypes, if and what SSL certificates are needed.
Troubleshooting
The troubleshooting documentation helps when running into production issues. Most technical
issues should have error codes that should help with troubleshooting. In this document there
should also be included an FAQ section to deal with general or usual problems (such as
configuration issues). The errors should be documented split by type of error, module where it
comes from, and level of error (exception, warning, critical, etc...).
Application Installation
Installation and configuration documents are useful for when developers need to set up new or
additional application environments. If possible, the steps should be detailed and easy to
follow and can include screenshots if necessary. Anyone should be able to follow the steps and
successfully install an application. Having the steps identified will help the installer prevent
problems because of missing parts of an application. Details such as necessary software,
libraries, and application server versions, can be included to ensure the environment will be
compatible and set up as intended.
Code
The code documentation is the backbone of every application. Code documentation can be split
in multiple parts. The first one, the most helpful for programmers are the comment blocks.
These will be found through every file explaining classes, methods, parameters, possible errors.
Then comes the specific file documentations. These are usually generated through a third party
script which will parse a file and, based on the comment blocks, will create an explicit PDF.
Afterwards there should be information regarding the code repository, where the file updates are
found, and where they need to be moved. In addition, there should be step-by-step instructions
on how to create an application package or a build to be deployed.
Levels of System Documentation:
Levels of documentation mean the persons or positions in the managerial hierarchy for whom or
to whom document is useful for operation purposes.
These levels are:
1. Documentation for users
2. Documentation for management
3. Documentation for data processing department.
1. Documentation for User:
For the smooth operation of the system, it is essential that the users understand the system fully,
and are aware of what is expected of him to make it work successfully.
1. The documentation should include a sample of each input document and instructions for using
it.
2. It should also indicate operating schedules.
3. User’s documentation should cover files layout and file relation details.
4. The documentation for user should explain in non-technical terms all aspects of the system
from users’ point of view.
5. It should also explain how the system will operate once it is fully installed.
6. It should include a sample of each output report with necessary explanation.
7. It should state the input document coding procedure, and also the coding structure for various
fields and related tables.
8. Limitations of system should also be highlighted.
2. Documentation for Management:
It includes systems’ proposals covering the followings:
i. Functional Design—Functional requirements.
ii. Resources required.
iii. Cost benefits analysis.
iv. Development schedule.
v. Concepts, architectural design.
3. Documentation for Data Processing Department:
This has been divided into following three categories:
(a) Documentation for system’s designers.
(b) Documentation for operations personnel.
(c) Documentation for programmers.
(a) Documentation for System’s Designers:
It includes:
(i) Layouts of master files
(ii) Layouts of intermediate files
(iii) Controls
(iv) I/O schedules
(v) Output report layout
(vi) System flow chart
(vii) Implementation plan
(viii) Copy of program specification
(ix) Input from layouts.
(b) Documentation for operations personnel:
This has three sub-groups:
1. Machine operations—this should include:
(i) Detailed instructions for each step.
(ii) File retention schedules.
(iii) Interrupt/Restart procedures.
(iv) J.C.L. Listings for each step.
(v) Systems flow.
2. Data preparations:
The documentations should provide samples of all input documents, card layouts, record layouts,
special instrument for data preparations, retention schedules for data.
3. I/O control:
(i) Quality control checking procedures for each step.
(ii) Despatching (reports) details
(iii) Processing schedules
(iv) Document receipt details.
(c) Documentation for Programmers:
For each program there should be a program folder covering the followings:
(i) Source program listing.
(ii) Development of system test run.
(iii) Program specifications I/O layouts.
(iv) JCL listing.
(v) Usage of any special technique
(vi) Test results
(vii) Test data listing
(viii) Program logic flowchart.
(ix) Changes in specifications during program.
The final document or final report should be professionally typed and bound with clear
illustrations with limited technical terms. If top executives of the organization can grasp the concepts of
the new system, they are likely to show appreciation and support future projects.
