Documentation standards and importance

We use a set of requirements documentation standards to have consistency in our writing styles.

Document requirement in appropriate and suitable format

Many people search one type of document design. That is answer to all requirement need. but the truth is this does not exist, it differ from organisation to organisation.

Even through there are few pre-define documentation standards for example-

IEEE 830-1998 standard to prepare table of content.

Every organisation have their own documentation standards.

Requirement documentation can take various formats as long as it is well understood by various stakeholders

Documentation is often combination of natural language used with relevant structure diagrams and notations’

Importance for documentation standards

1. Requirement documentation standards forms the base for rest of project life cycle, Therefore, it is important to document requirements for data analysis, design and implementation activities
2. where an organisation is working with different departments or external solution providers. This requirement document forms a part of legal document contract are agreement between different parties
3. the simple matter of complex requirements inhibitively required suitable data requirement documentation in order to keep track of dependence, complexity and record of what is required for future system
4. Having the requirements documented provide good reference point for any stake holder or new project team members to refer throw

Comprehensive requirement documentation facilitates the ability to establish common understanding among many stakeholders and team members which aids in efficient progress as a team

examples of requirements documentation standards

• Requirements should be written in the form of “subject” shall “action verb” “observable result”.
• For example, “System shall display a list of all containers of the requested chemical that are currently in the chemical stockroom”.
• Use the words such as “User” and “System” to represent subjects in active voice sentences.
• Use case names should be of the format “Perform Action on Object”
• For example, “Add Item to Cart”. If the same functionality is described in multiple use cases because the actor is different in each, then add “for actor” to the end of the use case names.
• Each step in the use case should describe “single action” by the user or the system.
• Multiple actions of user or the system should not be combined into a single step.

The consistency gain from standards will improve readability, which intern make quick understanding to someone what is written.

All the members on the receiving end of the documentation can become familiar with one style, so that the time spent reading the documentation will be focused on content rather than learning the author’s language.

Writing in similar styles allows someone new to the project context to review the document and focus on the content.

Similarly, it helps to simplify the review process of documentation with in a team.

Documentations standards adds benefits to the organization

Team can work together to develop the standards in organization or project. Once the standards are decided,

they will not waste time on silly debates like, how to name use case, the number of spaces between sentences OR the use of active or passive voice,

The more productive suggestion is to have the debate periodically and decide as a team on a standard and move on to implement it.