Strictly structured documentation

UMP approach to minimization of the documenting process

The following principles will allow to minimize the documenting process:

1. Put in the documentation only the information which cannot be formalized and incorporated directly into programs or models. Read explanations below on this page.
   
   
2. Put in the documentation only such information, which makes development, further maintenance and evolution of the software be reasonably independent of individual team members.
   
   
3. The documenting process accompanies all other processes. The UMP prescribes the documents which should be used in all UMP tasks.
   
   
4. The documentation must be kept to the planned minimum necessary volume sufficient for the project completion: document only the information which should be retained. Explain why the information should be retained and for how long. See UMP recommended set of documentation >>
   
   
5. The documentation should be strictly structured. Read explanations below on this page.
   
   
6. The documentation should not drop below the minimum planned acceptable level of quality.
   

Project deliverables and documentation

• Programs: source code, its derivatives and data, necessary to run software
• Models: formal description of the software, e.g. UML models
• Documents: text, possibly illustrated with graphics, charts, tables and all that

The distinctive features of these deliverables types:

• Programs: written in strictly defined programming languages (source code), automatically generated by the programming tools (source code derivatives and data)
• Models: developed using more or less exactly defined visual languages, such as UML; usually graphic schemes
• Documents: hand-written or hand-drawn (even with the use of computer); lack of formal rules, structuring etc. is admissible and even inevitable

Why do we need to waste time on models and documents instead of focusing on the program itself? As regards the models the answer generally is: the software developed on the base of the models is more reliable. In UMP this statement is not discussed but accepted as an axiom.

The following project information cannot be put into (or presented by) the programs or models:

Documentation required by sponsors and customers is defined outside of the development process and is not considered in UMP.

Rules for the strictly structured documenting process

• Separate facts from examples, explanations and reasoning. Those who understand facts do not need to waste time reading explanations.
• Condense text: avoid adjectives.
• Use bulleted lists instead of in-line text blocks.