Skip to Content
Technical Articles
Author's profile photo Klaus Haeuptle

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

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.

Assigned Tags

      11 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo DJ Adams
      DJ Adams

      Nice post Klaus.

      I've heard some folks say that treating documentation as code, using collaboration and content management facilities such as those that GitHub offer, is "too much" for non-developers. To that, I gently say "nonsense" 🙂

      To treat documentation as anything other than valuable content that deserves scrutiny, love, attention, and collaboration to pinpoint accuracy, is to do a disservice to that documentation.

      Author's profile photo Klaus Haeuptle
      Klaus Haeuptle
      Blog Post Author

      Git and Markdown is not hard to learn. Actually Markdown is the simplest syntax I know. And I guess engineers could do some quick pair programming with product managers, product owners, documentation colleagues and others to help them get started.

      Author's profile photo Matthew Billingham
      Matthew Billingham

      Goes hand in hand with treating code as documentation!

      Author's profile photo Klaus Haeuptle
      Klaus Haeuptle
      Blog Post Author

      Completely agree! Treating code as documentation is also an important aspect of Clean ABAP and Clean SAPUI5.

      Author's profile photo Helmut Tammen
      Helmut Tammen

      Nice and short 🙂 summary. Thank you.

      Author's profile photo Klaus Haeuptle
      Klaus Haeuptle
      Blog Post Author

      Thanks for the feedback!

      Author's profile photo Suhas Koul
      Suhas Koul

      I can also recommend mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs. (mermaid-js.github.io)

      as well for documenting certain TAM diagrams in the repository.

      Best Regards

      Suhas Koul

      Author's profile photo Klaus Haeuptle
      Klaus Haeuptle
      Blog Post Author

      Thanks! I am also using Mermaid - added it to the blog.

      Author's profile photo Lubomir Markovic
      Lubomir Markovic

      Our team has the documentation of each app  in many JIRA tasks as they come during the time.

      It was a shock for me when I joined the team. It is _very_ difficult to find any info and you are still not sure whether some newer issue did not change it.

      I was also playing with summarizing the text of jira issues in GIThub (markdown+plantuml), then in Wiki (+draw.io) but for me as a developer and not the primary doc creator (as PO is) is very difficult to keep such doc in sync with  changing text of JIRA issues.

      I think this initiative has to target not to dev only but to PO especially. I am afraid  Mermaid/plantuml, even git and maybe even Markdown is beyond the technical level they (some of them) want to cross.

      I do not criticize it I understand that their focus to other things on the other side it is very diffulct to find the right tool to be simple enough, powerfull enough with desired expressivity (diagrams, pictures) supporting versioning and ideally kind of merging as well.

      I started to use Obsidian that seems to me very handy for personal notes keeping now,

      I can imagine using it for documentation purposes as well, but not tried yet.

      I am looking forward for some progress in this theme 🙂

      Author's profile photo Antonella Stella
      Antonella Stella

      Hi Klaus,

      Thanks for this blog post. It’s great to find somebody who shares our commitment to quality documentation! We, the central User Assistance infrastructure team at SAP, agree that bringing developers into the picture to increase product documentation quality is a fantastic idea, and the SAP open documentation initiative clearly goes in this direction.

      But it can be a challenge! We’ve seen individual development teams at SAP set up and run their own “docs as code” approaches, using different open source tools to produce output, creating individual extensions of markdown, and so on. And we need to consider some overall SAP challenges, such as content reuse, translation, terminology integration, and integration with software versioning and feature flagging across multiple products. And then we need to bring it all together in the SAP Help Portal (as the standard channel for delivering product documentation).

      As it happens, we are currently developing a set of best practices for “docs as code” approaches at SAP. If you’re up for it, we’d love to hear more about your experiences, and get your feedback on our recommendations. Let me know and we’ll keep you in the loop.

      Best,
      Antonella

      Author's profile photo Klaus Haeuptle
      Klaus Haeuptle
      Blog Post Author

      Hi Antonella,

      thanks for the feedback. I am interested in those challenges and practices! I'll setup a meeting to discuss the details.

      Let me also know if there are some practices or tools, which can be linked in the initiatives section. I did not include some topics for which I was not sure if they are relevant for customers and partners.

      Thanks and Regards,

      Klaus