Note: This is only a small reminder for myself and not a full article. You can write books about this topic.


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.


  • Markdown as text based markup language
  • PlantUML: UML generation from text files.
  • arc42, you will find different templates under Download