Note: This is only a small reminder for myself and not a full article. You can write books about this topic.
Introduction
Architecture changes over time and sometimes it is not easy to keep the documentation up-to-date. As a result you get an invalid description of your architecture.
The Problems
- Architecture is not created by only one person, but - over time - by multiple persons.
- Often architecture is documented far away from the source code or repository in Word documents or wikis like Confluence
- Changes are therefore not documented and later on nobody knows what information is still valid and which information was not updated.
- Usage of binary file formats like docx (Word) for example are bad to version: you don’t see the detailed changes. What you get instead is the whole document as a new binary file.
The solution
- The best practice would be to document changes in the same repository like your code.
- Use text based files, like markdown, which can be used to generate the documentation.
- The generation of the documentation can be integrated into the build process. (Gradle/Maven)
- You get a changelog for free: A big plus is that they are text files, which allow you to see all changes in detail instead of a change of the whole file like it is the case with binary files(docx).
- Use templates like arc42 and fill them with your data.
- For UML you can use PlantUML, which allows you to describe you UML diagrams as text.