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

[haeuptle]

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.

[qmacro]

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.

[matt]

Goes hand in hand with treating code as documentation!

[htammen]

Nice and short 🙂 summary. Thank you.

[SuhasKoul]

I can also recommend mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt cha...

as well for documenting certain TAM diagrams in the repository.

Best Regards

Suhas Koul

[haeuptle]

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

[haeuptle]

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

[haeuptle]

Thanks for the feedback!

[haeuptle]

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.

[antonellastella]

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

[haeuptle]

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

[markoviclu]

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 🙂

[henriquemattos]

Maybe the other way around would also be interesting. How about inviting Antonella for a presentation on the Ecosystem talks about the challenges and deliveries of the UA team at SAP?

I would be interesting in joining. 🙂

[haeuptle]

We had already a conversation and I have offered to have such a session in the Ecosystem.