Documentation Guidelines - Requirements Engineering and Management for Software Development Projects - page 224

Appendix A
Documentation Guidelines
A.1 Introduction
The language of English or perhaps every language, for that matter, is especially
rich in vocabulary with many words with almost the same meaning except for
subtle variations. The grammar allows free-flowing writing and in a poetic manner.
It is possible to write grammatically correct language yet obscure the real meaning
behind the write up. Well, poetic language is best for writing poems and flowery
language is fit for writing novels. But if we use those features of the language for
capturing and recording requirements for a software project, it would be very
difficult to proceed with the next steps of the project. Again, such language would
not allow us to ensure that the requirements are met because of the ambiguity.
In requirements specifications, we need to use the language to mean precisely
one thing that is interpreted by all stakeholders in the same way. Therefore, we
need to restrict the freedom of individuals involved in requirements engineering
work in documenting the requirements and provide them guidelines so that all
those involved in requirements engineering would document the requirements
specifications in a similar manner. Every organization ought to have a set of
documentation guidelines for business writing and most professional organizations
would have such documentation guidelines.
Here is a suggested set of documentation guidelines and these can be adopted in
your organization as it is or with modifications to suit your unique needs.
A.2 Documentation Guidelines
This guideline covers primarily the method of presentation, composition and
editorial practice to be followed in the preparation of requirements engineering
documents.