Documentation Is Fuel For AI
Fuelling The AI Engine
We all know how important it is to put the right fuel into an engine to get the best performance out of it. The same is true for AI engines.
Documentation is not only crucial for training AI models but also for driving and steering the productivity of Generative and Agentic AI tooling within Specification-Driven Development (SDD).
High Quality Documentation Is High Quality Fuel
Documentation is the fuel for AI! The better your documentation, the better the AI and the higher your productivity with AI tooling.
The quality of documentation has never been more important than it is now in the age of AI. Incomplete, inaccurate or ambiguous documentation will lead to poor productivy as unnecessary iterations are consumed trying to get the AI to understand what you are trying to achieve.
As we move beyond prompt engineering and into the brave new world of Specification-Driven Development, the quality and structure of our existing documentation will be a significant factor in the adoption of AI tooling.
Documentation Debt Is The New Technical Debt
We are all familiar with the term "Technical Debt" and how it can hold back development teams and lead to increased costs and reduced agility. In the age of AI, documentation debt is the new technical debt.
Poor quality documentation will lead to poor performance from AI models and tools, which in turn will lead to increased costs and reduced agility.
One of the best strategies for technical debt is simply to "stop creating it". The next step is to identify and prioritise the remediation of that technical debt as part of your on-going work which degrades future productivity until the problem is dealt with (or abandoned).
However, the documentation debt we are likely to encounter as a result of the uptake of AI tooling for SDD purposes may prove unavoidable if the structure and content of our existing documentation does not immediately lend itself to SDD needs.
SDD Documentation Needs Are Different
The documentation needed to drive Agentic AI tooling within SDD is different to the documentation required to construct technical solutions today.
Whilst the structure and content of your existing documentation may have served you well in the past, it may not meet the demands of Agentic AI tooling.
Whilst SDD still supports iterative and incremental development, SDD takes software development very much back to the waterfall approach where getting the specification right is highly important. "Garbage in" will certainly lead to "garbage out" with AI tools.
There is no place for incomplete, inaccurate or ambiguous documentation when it comes to driving Agentic AI tooling if you wish to minimise iterations. The AI will take your documentation very literally and will not be able to read between the lines. This means that you need to be very clear and precise in your documentation and ensure that it is of high quality i.e. accurate, unambiguous and complete.
Unfortunately software development is not just about functional requirements. Non-functional requirements are equally important as are the many other types of documentation that determine how technical solutions are designed, built and operated today. All of these will need to be presented to the Agentic AI tooling.
Previously, the vast array of document types and formats may have been located in many different repositories and owned by different teams. Now, with the rise of Agentic AI tooling, there is a need to bring all of this documentation together and ensure that it is of high quality and easily accessible to the AI models and tools that need it.
With Agentic AI tooling, it can be just as important to say what you don't want as it can to say what you do want. This may prove to be a significant change in how we need to think about documentation and the content that we need to produce.
There is also a greater need to prove that the automated coding performed by the AI tooling is correct and indeed meets the requirements specified in the documentation. Thousands of lines of code may have been produced in seconds by the AI tooling but if it cannot be easily and quickly proven to meet the requirements then it is of no value.
Automated quality gates must act as guardrails to provide transparency, enabling confidence and trust in the hands-off code produced by the AI tooling. Additional code analysis and tooling process steps may be required to gain that assurance as well as increased numbers of tests and levels of coverage.
No Free Lunch
There is no free lunch when it comes to documentation. It takes time and effort to produce high quality documentation and this is likely to be a significant barrier to the adoption of Agentic AI tooling. Especially when the skills and knowledge may currently be spread across multiple individuals and teams.
Documentation Is The New Component Technology
Just as we re-use common components in our software development, we should expect to re-use documentation in our AI development.
Today, we re-use specialised components for specific functionality and so within SDD we will likely need to re-use specialised documentation to specify common technical requirements such as solution architecture, preferred technology stacks, coding standards, security best practices etc.
Will AI Development Really Take Less People?
Software development has traditionally relied on specialisation of labour which typically manifests in project teams of multiple individuals skilled in particular roles embracing specific tools, technologies and techniques as part of their daily work practices.
It is not easy for an individual skilled in one role to transition into a different role that embraces different tools, technologies and techniques. Not all individuals have the same levels of experience in their given role.
Promises Promises
The promise of AI development is that it will take less people to achieve the same outcomes in less time. This may be true in some cases but if the AI tooling requires a greater emphasis on more exacting documentation, then this promise may not be fulfilled if the creation of such documentation requires the specialist skills of many roles.
Whilst Agentic tooling may achieve higher levels of producitivy for some tasks this may be offset by the time and effort required to produce the documentation required to drive the AI tooling and additional proving iterations.
Anyone who has failed to automate testing in the past will be swept away by the need to automate the proving of the code produced by the AI tooling to an even finer level of detail than before in order for that code to be both verified and trusted.
Rapid coding iterations demand equally rapid testing that can only be achieved through test automation. Requirements must be expressed in such a way that they automatically drive out acceptance criteria that can be automatically tested.
Productivity Promises Yet Unproven
Whether Agentic tooling can do everything that the hype says it can is currently unproven.
It all sounds too good to be true and so many are not hesitating to try it out for themselves, fearing their competition will get there first and gain significant advantage and future market share.
Documentation Yet Unproven
Will your documentation meet the needs of AI tooling or will documentation debt hold back your AI ambitions?
Will the quality of your documentation fuel or hinder your AI ambitions?
How will your teams adapt to the new documentation needs of AI tooling?
Don't wait to find out. Start now to understand the documentation needs of AI tooling and to assess the quality of your existing documentation and to address any gaps or issues.
The race is on! Time will tell.
Thank you for liking this page.
Tim Simpson
30th April, 2026
#AI-Productivity | #LifeAtCapgemini