Peter Verhas, EPAM Systems, Senior Software Developer
The code is best documented by itself. This statement is interpreted many times as an argument not to write documentation. This is absolutely wrong, but the original statement is not. Software documentation describes something which is already there in the software. Document writers in English feature often copy information from the program. Why not automate the part that could be automated? Not everything. Many times sentences should be written in English, and this cannot be done by a program yet. But file names, configuration parameters, version numbers, and many other things can be automatically fetched from the source code. You can mark each section of the documentation that is about a certain feature implemented in a specific file, and the documentation processing can warn you when the implementation has changed.
Jamal at
https://github.com/verhas/jamal is a general-purpose text processing tool that can work and help you maintain your documentation no matter what format you use. You can use any text-based document, like AciiDoc, Markdown, or Microsoft Word, and include processing instructions in your documentation.
You can include and reformat code snippets, import and reformat documentation from source code comments, check that certain methods, fields, classes, and configuration parameters exist in the program, reference configuration values in the document, define macros for repeated texts, check the consistency of the documentation with the code and to other text documents.
Using Jamal, you will never need to write "latest version" to avoid copying the version number or being afraid that you will forget and your document will become inconsistent and outdated.
The talk is about the theoretical background, discusses documentation cohesion and consistency, and shows the use of Jamal in a demonstration using IntelliJ and AsciiDoctor plugin WYSIWYG editing.
