Documentation and Standards

Obviously, I believe there is a significant place for documentation, or I would not be working on this project. You would not be reading this text if you did not believe the same. There is a time and a place for documentation and standards. When documentation and standards increase productivity, they should be used. When they decrease productivity, they should not be used. A fairly simple rule.

This Project

This project is a good example of the application of documentation, standards, and recommendations. The documentation on this project has a specific purpose. It is to make learning faster by being as brief as possible, yet convey proper meaning. It is also to be used as a reference. Documentation produced in all organizations should be closely aligned with the goal of the documentation or it is counter productive. Some specific goals may be:

  • To inform a user about how to use a system.
  • To document programs to the extent that other programmers may work on them efficiently.
  • To teach.
  • To be a reference.

Standards

All organizations need standards. Even this organization has standards. Standards should enhance productivity, and not prevent productivity or creativity. The organization should have no more than 10 pages of standards or they become useless since no one will want to read them. The potential purpose of standards should be:

  • To increase organizational cohesiveness and communication with unified methods.
  • Offer gently guided convergence.

Recommendations

Recommendations can supplement standards and therefore fewer standards may be required. They can be used to hold up a goal to the organization teams for how to do things, but recommendations allow for the flexibility to not always adhere to them. This way creativity nor production is not stifled. This organization uses recommendations as much as possible to allow for as much material as possible to be submitted. If standards were imposed, some material may not be imposed due to the overstrictness of the standards. Obviously, there must be a minimum, and this is where standards should be applied.

Types of Documentation

  • System documentation - For management describing how the system works summarizing subsystems, interfaces, features, capabilities.
  • Program documentation - Describes the software program logic and how it relates to the system.
  • Operations documentation - Procedures used to execute system jobs.
  • User documentation - How the user can use the system and how they input data.