by Patrik Hermansson

• Abstract
• Chapter 1 - Different types of documentation
  • Technical documentation
  • Descriptive documentation
  • Policy documentation
  • Mix-mode documentation
• Chapter 2 - Why do we need documentation?
• Chapter 3 - For whom is the documentation?
  • For collaboration

Documentation is a loose concept. This document is a try to clarify about what documentation is and how to use it from a technologically point of view. Some (but not all) things to answer:

• Different kind of documentation.
• Why do we need documentation?
• Collaborate or not?
• The importance of updating the documentation.

Let’s dive in …

Examples:

• Code in repository (like GitHub or GitLab).
• Detailed technical documentation of servers, firewalls or similar.
• Electrical schematics.
• Recipe in a cookbook.

Descriptive documentation is usually an overview over something. A more top view on how things are working. Little or no technical information is included. Examples:

• A network schematics over a network or setup with several servers.
• A flow chart describing on how a program or script is working.

Policy documentation differ from the other kind of documents described here because the matter of the document is more abstract than in the others. A policy documentation is more of an ide on how to proceed, whereas the other documents shows more detailed view on how the world are in a model (Descriptive) or down on a detailed level (technical).

This is documentation, usually for project planning, that includes both parts of the technical and parts of the descriptive documentations. This kind of documentation is good for planning new setups and changes in current setup, programs or similar.

This might feel like a silly question and maybe the question should be “Why is documentation so important?”.

For my personal opinion, the documentation is very important. It is the foundation to the decision for the program, the setup and / or the function implemented. And it is the foundation for good maintenance of the function or program.

Without good documentation there is a big risk that the program is full of bugs that are not fixed or that the system(s) are not patched or updated. New functions are not implemented and maybe even so bad that the system or program is forgotten.

The documentation should include some kind of plan for the future and -/or lifecycle management.

Is it just for the little team or single person or for a bigger group? Mabey the whole company?
Will there be one author or is it a collaboration between several parties involved in the documentation?

Tools like DokuWiki, Sharepoint, Jira enterprice can be used to make it easier to collaborate in the documentation.
If the content of the documents is of a sensitive sort. Then a granular restriction function should be implemented. Identity control and authentication should always be part of the process of choosing the collaboration tool.