Documentation as Code: Improve the quality of documentation, decisions, communication and meetings

This blog is about an important principle for improving the quality of documentation. It can also help to improve decision making, collaboration and more effectively use meeting time by leveraging written asynchronous communication.

Documentation (e.g. Architecture Documentation, Good Practices and Product Documentation) should be treated as code, which means that it is:

• placed under version control
• very simple syntax
• changes undergo reviews
• issues tracked (e.g. using GitHub issues)
• be checked for accuracy and freshness (e.g. automatic check to discover dead links)
• for Product Documentation the usage of feature toggles should be possible
• allow users of documentation to make proposals for improvement and open issues (important for community building)
• allows further automation (e.g. Jupyter notebooks, GitHub Actions, enriching information dynamically and more)
• large scale changes become easily possible
• efficient editing
  • no need to take care of formatting
  • enables use of IDE and text editor (e.g. block selection)
  • same environment as source code

Using other tools than the version control system for documenting often does not include the developers sufficiently in the writing process. With everything stored in version control, the same tooling can be used for issues, proposal of improvements and reviews. Engineer will be able to fix the documents themselves or propose changes to technical writers. Therefore the maintaining documentation need to become a similar experience as maintaining code. Leveraging this existing developer workflow will result in higher quality of the documentation.

Another main use cases is the replacement of wiki pages. Especially with large groups of potential contributors, Pull Request can help to review and incorporate changes from everywhere and create a community around a central knowledge hub.

It can also help to improve alignment across team and architecture decision making with RFC (Request for Comments) as a means for exploration, collaboration and discussion and ADR (Architecture Decision Records) for documenting architecture decisions.

Initiatives

• • SAP’s new Open Documentation Initiative
  • Clean Code for ABAP
  • Architecture Decision Records
  • Mermaid: Creating visual diagrams in Markdown
  • Presentation as code
  • Optimized Websites based on Markdown with Docusaurus
  • Write the Docus: Docs as Code Community with lots of learning materials and a conference

Subscribe to Newsletter: Collaboration on Improving

If you do not miss an update on Clean ABAP, Clean SAPUI5, test automation, testability and other engineering / craftsmanship / architecture topics, subscribe to the brand new newsletter. The newsletter will not only be used for sharing knowledge, but also offer opportunities for collaboration, building communities and co-creation.