Documentation issues

Article#: 00075

Date: 2021-12-11

Author: Radim

What documentation problems are there?
1. Creation of the documentation is very time-consuming / financially expensive.
The subsequent writing of a complete and usable documentation of a program is very time-consuming - at least as time-consuming as writing of the program itself.

2. Creating documentation is a boring task for software developers.

3. The documentation does not correspond to the program if additional changes have been made to the program (e.g. hastily during commissioning) and new functions have been added that are no longer entered in the documentation.
If the documentation is not updated with new program changes, it quickly happens that such documentation is completely unusable because it provides the reader with misinformation from which the reader can make a wrong judgment, and it quickly happens that no one knows what is actually right in the documentation. Bad documentation is worse than no documentation.

4. The documentation does not contain the information and details that we would need to get answers to the questions and to analyze a problem.

5. The documentation is written incomprehensibly (very briefly or very "professionally") and is not understandable for a "normal" person.

How do we avoid documentation problems?
1. Do not leave the documentation process until the end of the project. Document every ongoing project phase - project assignment, use cases, requirements, solutions, decisions, functional description, program model, test scenarios and test results, ideas for improvement, ...

2. Divide program into modules.

3. Write readable code.

4. Before you start programming, find a way how to automatically export program documentation from program declarations, definitions and comments. That way we don't have to worry about the documentation not following the program. We simply export the corresponding new documentation after every program change.

5. Comment on the program, what and why the program is doing. Also, consider how you write comments to make the auto export helpful for readers.

6. Create a visualization that clearly shows how the machine is controlled and what the program is doing.

7. Write a user manual for the HMI and integrate it into the visualization.

8. Ideally, the project and program are automatically documented without any further effort.

If the program documentation is created separately, it is practically impossible to keep the documentation up to date. Often a programmer does not even know that he is changing something that is documented elsewhere.
If the documentation is separate, you will not notice the deviations from the program.
Therefore, a well-commented program code is the best documentation. Here the programmer notices immediately if the comment does not correctly describe what the program is doing.
In addition, a well-designed visualization is great documentation that explains how things work on a machine, and you will quickly notice if the visualization does not match the program on the machine.

© Radim-Automation, 2020–2025. All rights reserved.
Sharing of this article is permitted with proper attribution (link to the original page).

Related previous articles:

Related next articles:

Comment#: 00001

Date: 2021-12-11

User: Radim

"Really readable code is almost as easy to read as any other technical text.
On the contrary, an illegible code, which has to be deciphered with every reading, does not fit the documentation and needs another detailed document that explains its function.
Entering the code correctly therefore saves some of the boring work involved in creating the technical documentation."
- Petr Paleta. Computer Press (2003). Co programátory ve škole neučí.

Comment#: 00002

Date: 2022-10-22

User: Radim

"The business world is littered with dead documents that do nothing but waste people's time. Reports no one reads, diagrams no one looks at, and specs that never resemble the finished product. These things take forever to make but only seconds to forget.
If you need to explain something, try getting real with it. Instead of describing what something looks like, draw it. Instead of explaining what something sounds like, hum it. Do everything you can to remove layers of abstraction.
The problem with abstractions (like reports and documents) is that they create illusions of agreement. A hundred people can read the same words, but in their heads, they’re imagining a hundred different things."
- Jason Fried, David Heinemeier Hansson. 37signals (2010). Rework.

Comment#: 00003

Date: 2022-11-03

User: Radim

"The inherent complexity of automation requires extensive documentation to define the requirements and maintain the resulting assets. The documentation is also very interdependent. A simple change can affect multiple documents. Something as simple as changing an instrument tag affects the piping and instrumentation drawing, I/O list, instrument specification sheet, distributed control system (DCS) database, field junction box drawing, marshalling cabinet drawing, and loop sheet. As a result, documentation is difficult to keep current and accurate throughout the project."
- https://blog.isa.org/industrial-automation-projects-challenging-management

Comment#: 00004

Date: 2023-06-16

User: Radim

"I see 5 main requirements for the documentation:

1. Multi user capability - because there will be many authors contributing to the documentation.

2. Capability of versioning - because of the fact that several users will be working on the documentation, it is required that the documentation is compatible with 'git' (or any other versioning software). The reason for this requirement is, that the documentation of certain toolchain elements (for example software) must match with the version of the documented element in order to provide correct information.

3. Offline availability - because the developers who implement software do not necessarily have access to any cloud. They might be somewhere outstation sitting in a spinning mill without internet, but with questions that requires the documentation. The 'office developer' is not the regular user of the documentation, real life is at the front with bad conditions. For this reason, some parts of the documentation must be kept together with the code to be checked-out at the same time.

4. Full congruence between software and documentation version - because the developer looks for answer related to the project version he is working with.

5. Overall information about related software parts as well as detailed information about specific functions, their behaviour and usage. Therefore extracted comments from the source code, as provided by doxygen, most probably won't be sufficient, because they don't give the overall information.

My conclusion:

The documentation (at least this part which has the function of a user's manual to the developers) must be an integrated part of the project and stored together with the project - i.e. documentation package as a part of the development environment. This will satisfy requirements no. 3 and 4

The documentation must be written in a markup language (HTML, XML, LaTeX etc.) to ensure that it can be handled by git. This will satisfy requirements no. 1 and 2.

There won't be a cheap and easy way to get a hi-level documentation, the project is far too complex for that. It has to be written word by word, the sooner we start the better.

Having a technical redactor who coordinates all the documentation and makes sure that all the documentation is structured and didactically valuable is crucial.

Not investing from the very beginning in a sustainable and long-life solution for the documentation will result in loss of know-ledge within short time."

- Christian Vetterli

Comment#: 00005

Date: 2023-07-28

User: Radim

The documentation should also be printable on paper so that it can be easily read without a PC monitor. It is therefore necessary that the tool/application in which we have the documentation in electronic form is able to print the documentation legibly on standard A4 or A3 paper, respecting the formatting of text and graphics is.

Comment#: 00007

Date: 2024-02-22

User: Radim

Is your native language not English and do you work in an international team? Have you agreed on English as the project language within the team? Then please:

1. Install and use all project tools in English.
2. Use English help files for the tools.
3. Write English variable names and comments in the code.

These rules make collaboration between team members, documentation and support tasks easier. Because people will use the same terms.

Do you agree with these rules?
Would you add anything else?

Comment#: 00008

Date: 2024-04-09

User: Radim

Proper storage of information is crucial for efficient work and easy and quick access at a later date.
A good archiving structure and discipline helps to maintain clarity and structure in the working environment, which contributes to the productivity and success of the project as a whole.
It is therefore important to pay sufficient attention to where and how information is stored and to follow appropriate archiving and organization procedures.

User:

Log in user:

Log in user:

Log in user - Failure:

Log in user - Failure:

Request password:

Request password:

Request password - Failure:

Register user:

Register user:

Register user - Failure:

Register user:

Register user - Failure:

Register user:

Register user - Failure:

Register user:

User settings:

User settings:

User settings:

User settings: