Documentation as Code: Improve the quality of documentation, decisions, communication and meetings
This newsletter edition 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
Why: More on my motivation to start the newsletter can be found in Collaboration on Improving: Why I'm starting the Engineering Ecosystem.
About me: I am Klaus Haeuptle an engineer and architect at SAP, the author of the books Clean ABAP and Clean SAPUI5, a coach for agile software engineering and a community servant leader for a large SAP internal grass roots community on improving tools, technologies, practices and culture, with more than 3000 participants from all locations and departments. Views are my own - the content published on this channel reflect my opinion and engineering principles.
Subscription: If you want to get updates, you can subscribe to the free newsletter:
Mark as not spam: : When you subscribe to the newsletter please do not forget to check your spam / junk folder. Make sure to "mark as not spam" in your email client and move it to your Inbox. Add the publication's Substack email address to your contact list. All posts will be sent from this address: ecosystem4engineering@substack.com.
✉️ Subscribe to the newsletter — if you aren’t already.
❤️ Share it — The engineering ecosystem newsletter lives thanks to word of mouth. Share the article with someone to whom it might be useful! By forwarding the email or sharing it on social media.