Don't document your code; code your document.
Documentation is essential, and at the same time, it is part of the software products that usually contain the most bugs. For example, documentations tend to be outdated, have wrong references to the documented system, and may contain inconsistencies. The compiler or the unit tests discover the same type of errors in a program code. Documentation does not have such a compiler or tests. Writing documents, we still do assembly.
The principles for high-level documentation coding are:
Do not copy information from the documented system to the documentation manually. Automate your document compilation.
Keep documentation sources close to the system.
Do not repeat yourself in the documentation, and do not copy-paste text.
Create unit tests checking the consistency of the documentation.
The talk will cover these principles and how to reach these goals using Jamal (https://github.com/verhas/jamal/), showing real-life examples.
The topic was described in detail in the article https://javax0.github.io/2021/02/17/automate-technical-documentation-using-jamal.html
Peter Verhas is a senior software engineer and software architect with having electrical engineering and economics background (MSC and MBA). He created his first programs in 1979. Since then, he has authored several open-source programs. He has worked in several telecommunications and finance industries positions and was the CIO of the start-up index.hu during its early days.Peter works for EPAM S...