What is Documentation ?
Documentation consists of instructions for using a computer device of program.
Documentation can appear in a variety of forms, the most common being manuals.
When you buy a computer product (hardware or software), it almost always comes with one or more manuals that describe how to install and operate the product.
In addition, many software products include an online version of the documentation that you can display on your screen or print out on a printer.
A special type of online documentation is a help system, which has the documentation embedded into the program.
Documentation is often divided into the following categories
1) Installation : Describes how to install a program or device but not now to use it.
2) Reference : Detailed descriptions of particular items presented in alphabetical order. Reference documentation is designed for people who are already somewhat familiar with the product but need remainders or very specific information about a particular topic.
3) Tutorial : teaches a user how to use the product. Tutorials move at a slower pace than reference manuals and generally contain less detail.
Need for Documentation
A software cannot be considered to be complete until it is properly documented. So proper documentation of software is necessary due to the following reasons.
More documentation means easier usage. As soon as a user gets stuck trying to get a program feature to work, he or she starts to read that program's documentation. Therefore, creating well-structured and well-written documentation will make it easy for the user to get that feature to work.
It makes program or software is easy to maintenance.
A well documented software is easy ti modify and maintain in the future.
It is easier to understand the logic of a program from the documented records rather than its code.
Flowcharts or comments used within the programs are very helpful in understanding the functionality of the whole program.
Documented records are quite helpful in restarting a software project that was postponed due to some reason or the other.
The job need not be started from scratch and the old ideas may still be easily recapitulated which saves lot of time and avoids duplication of work.(Reusability).
In general the following aspects of a program or project should be documented
1) Basic usage is mostly covered in a man page.
2) More advanced usage can be achieved by giving options in the documentation and giving examples on how to use them (take the very good Apache documentation for example).
3) Source code, of course, because somebody may want to add features to the program.
4) Example of usage (what input to give and expected output) to supply a working basic configuration file and document it heavily.
5) Installation of the program, because not all program work with easy ways.
Forms of Documentation
The three commonly used forms for documenting software are-
Comments
Comments can be useful for
1. Describing an element
2. Adding remarks and lists
3. Describing parameters
4. Describing methods/properties
5. Providing examples
6. Compiling the code.
System Manual
A document which is used to maintain all the system details and its usage is a system manual. It consist of
1. The objectives of developing the software and its usefulness to various categories of users.
2. Specifies program names along with their description and purpose.
3. Detailed system flow charts cross-referenced to the listing.
4. A source listing of all programs together with full details of any modifications made since.
5. Specimen of all input forms and printed output records.
User Manual
A document which is used by the user for understanding easy use(how to use) of any product is a user manual. It consists of-
1. Operational details of each program.
2. Loading and unloading procedures.
3. Starting, running, and terminating procedures.
4. A description and example of any control statement that may be used.
5. List of errors condition with explanations for their re-entry into the system.
6. List of program to be executed before and after execution of each program.
Documentation consists of instructions for using a computer device of program.
Documentation can appear in a variety of forms, the most common being manuals.
When you buy a computer product (hardware or software), it almost always comes with one or more manuals that describe how to install and operate the product.
In addition, many software products include an online version of the documentation that you can display on your screen or print out on a printer.
A special type of online documentation is a help system, which has the documentation embedded into the program.
Documentation is often divided into the following categories
1) Installation : Describes how to install a program or device but not now to use it.
2) Reference : Detailed descriptions of particular items presented in alphabetical order. Reference documentation is designed for people who are already somewhat familiar with the product but need remainders or very specific information about a particular topic.
3) Tutorial : teaches a user how to use the product. Tutorials move at a slower pace than reference manuals and generally contain less detail.
Need for Documentation
A software cannot be considered to be complete until it is properly documented. So proper documentation of software is necessary due to the following reasons.
More documentation means easier usage. As soon as a user gets stuck trying to get a program feature to work, he or she starts to read that program's documentation. Therefore, creating well-structured and well-written documentation will make it easy for the user to get that feature to work.
It makes program or software is easy to maintenance.
A well documented software is easy ti modify and maintain in the future.
It is easier to understand the logic of a program from the documented records rather than its code.
Flowcharts or comments used within the programs are very helpful in understanding the functionality of the whole program.
Documented records are quite helpful in restarting a software project that was postponed due to some reason or the other.
The job need not be started from scratch and the old ideas may still be easily recapitulated which saves lot of time and avoids duplication of work.(Reusability).
In general the following aspects of a program or project should be documented
1) Basic usage is mostly covered in a man page.
2) More advanced usage can be achieved by giving options in the documentation and giving examples on how to use them (take the very good Apache documentation for example).
3) Source code, of course, because somebody may want to add features to the program.
4) Example of usage (what input to give and expected output) to supply a working basic configuration file and document it heavily.
5) Installation of the program, because not all program work with easy ways.
Forms of Documentation
The three commonly used forms for documenting software are-
Comments
Comments can be useful for
1. Describing an element
2. Adding remarks and lists
3. Describing parameters
4. Describing methods/properties
5. Providing examples
6. Compiling the code.
System Manual
A document which is used to maintain all the system details and its usage is a system manual. It consist of
1. The objectives of developing the software and its usefulness to various categories of users.
2. Specifies program names along with their description and purpose.
3. Detailed system flow charts cross-referenced to the listing.
4. A source listing of all programs together with full details of any modifications made since.
5. Specimen of all input forms and printed output records.
User Manual
A document which is used by the user for understanding easy use(how to use) of any product is a user manual. It consists of-
1. Operational details of each program.
2. Loading and unloading procedures.
3. Starting, running, and terminating procedures.
4. A description and example of any control statement that may be used.
5. List of errors condition with explanations for their re-entry into the system.
6. List of program to be executed before and after execution of each program.
Posts
0 Comments:
Post a Comment