Docs as Code and Generative AI - A Perfect Match
Hey, I am Klaus Haeuptle! Welcome to this edition of the Engineering Ecosystem newsletter in which I write about a variety of software engineering and architecture topics like clean code, test automation, decision-making, technical debt, large scale refactoring, culture, sustainability, cost and performance, generative AI and more.
Docs as Code is an approach to documentation that treats documentation like code, using version control, automation, and collaboration tools to manage and maintain it. This approach has several benefits, including improved consistency, better collaboration, and increased efficiency. About the many benefits of Docs as Code I have written before in Documentation as Code: Improve the quality of documentation, decisions, communication and meetings. This time it is about the benefits of Docs as Code for Generative AI.
Benefits of using GenAI in combination with Docs as Code
Docs as Code is particularly beneficial for generative AI for several reasons:
GenAI Support in IDE Using the GenAI tools integrated into the IDE as for authoring of documentation (e.g. GitHub CoPilot) can be also be a great help for writing documentation.
Quality Assurance: With documentation as code, it's easier to apply quality checks with or without AI, such as linting, which can improve the overall quality of the documentation.
Automation: Generative AI can automate documentation tasks, and having documentation as code makes it easier to integrate these automated processes into the development workflow.
Structured Data: Docs as Code encourages the use of structured formats like Markdown, which are easier for AI to parse, understand and process.
Consistency: By using standards for documentation, it ensures a level of consistency that is beneficial for training AI models.
Collaboration: It facilitates better collaboration between humans and AI, as both can work on the same documents using the same tools. E.g. AI can help to write the documentation and humans can review it via pull requests or diffs.
Close to Source Code Documentation as code is often stored in the same repository as the source code or at least the same organization, making it easier for AI to understand the context and generate relevant content - which can be documentation or other artefacts like source code.
In essence, Docs as Code provides a framework that is inherently more compatible with the capabilities and needs of generative AI, leading to more efficient and effective documentation processes.
How Docs as Code can be further optimized for Generative AI
The blog Optimizing Technical Docs for LLMs describes some good and bad practices for structuring documentation for LLMs. It highlights the importance of using structure and providing context. Since the field is new many best practices need to emerge. So what is your opinion about the following questions:
What are your ideas on how to improve documentation in combination with Generative AI further?
How could the next steps of documentation architecture and documentation engineering look like to optimize documentation as code further and leverage further improvements?
How to ensure that high quality documentation is created?
How to make architecture documentation and requirements availaible for AI developer tools?
What is your experience with tools like CoPilot for Docs or Mintlify?
How can GenAI to continuously evolve the documentation?
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.
❤️ 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.