What happens if you don’t have instructions to follow? The board game “Six Month City” plays on this conceptwhich gives players a box of parts and an instruction manual in an unknown language, and allows players to see how it works. Hollandspiele, the game’s designers, say on their website: You never know if you got it right or not. We will never answer legal questions.
A fun challenge if you want to keep up. Unfortunately, if developers follow this logic and choose not to write well, they risk making themselves and future developers a bad experience – and the use of AI risks making the problem worse.
The need for documents
Documentation changes software from something that just exists, to something that can actually be used. Good documentation explains not only how to use the software, but also how it works, how it fits together, and what its purpose is. It means that knowledge can be transferred from the team that builds the software to those who rely on it – not just now, but also in the future. It makes sense of decisions made over the years and gives developers information they can use to fix bugs and build improvements.
Poor documentation not only slows down development and makes debugging difficult, but its effects can be multiplied. Misunderstandings can spread through codebases, creating problems that can take a long time to fix. The use of AI accelerates this problem.
AI coding assistants rely on text to understand how the software should be used. Apart from AI, there is the option of institutional knowledge, or simply asking the developer behind the code. AI does not have this preference and will confidently fill in gaps where no documentation exists. We are familiar with AI concepts – and developers will be looking for these types of errors – but the lack of documentation can cause AI to take a stab in the dark. Without good documentation, there is very little chance that any error will be picked up during the review.
AI relies on patterns to do its job, and when those patterns aren’t found, it will make predictions — and sometimes those predictions are bad. Photographers have had similar problems with Adobe’s “generative fill” feature, which is often unreliable, but if we don’t have the right information, the results are surprising. Without documentation, there’s a good chance you’ll end up with the code equivalent of the Bitcoin logo on your seagull photo.
Debug your documents
The key to preventing this problem is to treat documents the same way you treat code. If an AI agent, or another engineer, can’t complete a task using documents, that’s a bug – and it should be turned off.
Developers need to document the entire workflow: the complete path from environment development to production deployment, including failures and edge cases. It can be tricky to spot mistakes in your work, so AI can be used to help here, by following the end of the text and looking for where confusion and errors arise.
AI can also be used for scripting and often does a very good job of compiling scripts when presented in code. However, this should be treated like AI-generated code – it needs to be carefully checked for errors and omissions. It may also not fully understand why certain decisions are made, for example ways to fix certain critical situations, or choices to facilitate future development. Although developers enjoy working with code more than scripts, we can’t treat it as a one-click, AI-driven process.
Document creation should be an ongoing process – just as software is patched and updated, so should documents. Questions from support tickets and community forums – especially recurring issues – can be used to highlight issues in the documentation, especially those that result from hypothetical information. It can be tricky for experienced developers to keep in mind what others know and allow this in the documentation.
And like code, document development should be collaborative, with clear pathways for contributors to provide updates and make suggestions.
AI is only as good as the knowledge it has access to, and that makes documentation as important as code. But while human developers may make logical deductions where there are gaps, and ask for clarification where needed, AI coding assistants are more likely to make logical leaps and plow ahead with best guesses — leaving future developers with code that’s the size of a toy box of parts and no instruction manual.
