Code is crucial, but documentation of that code may maybe even more significant. No developer or software lives in isolation; until other developers can comprehend the code you have produced, it loses much of its potential influence.But what about the machines? Do they also require solid documentation?

The answer is affirmative, and it speaks to the future of “tiered documentation,” as stated by Vlad Ionescu. As he explains, tiered documentation involves “having one set of documentation for human users and another set of documentation specifically for LLM large language mode training.”

The former must be simple for humans to consume, while the latter must be detailed enough for technologies like Amazon Code Whisperer and GitHub Copilot to produce ever-improving code. It is an intriguing notion to increase developer productivity. So, what do we need to do to get there?

The Relevance Of Exceptional Documents

When you ask a developer what she needs to be productive, she will say “Great documentation.” For years, Slash Data has asked that question, and documents have topped the list:

This is, of course, much easier said than done. Even though we understand the necessity of documentation, for example, for conveying information, as developer Jeremy Mikkola suggests, it is consistently the chore that software engineers dislike the most. Producing decent documentation is hard, and does not provide the same enjoyment as writing the code.

According to coder Jakub Kočí, “the biggest problem in writing docs, is clarity.” After all, he says, “We are writing code for people first, not machines.” Creating a functional solution is only half the battle; structuring and maintaining it is typically the more challenging.

Kočí’s statement may have been accurate in 2022, but with the emergence of LLM-driven coding helpers like Amazon Code Whisperer or GitHub Copilot, it is now equally necessary for computers to comprehend your documentation as much as developers.

For example, Machines require different documentation than humans and are more thorough.

Introducing Layered Documentation

Ionescu advises experimenting with tiered documentation as a workaround for LLM code assistance. “Being dumb because doctors are dumb.” Some software firms attempt to address this by collaborating directly with partners to feed example code, documentation, and so on into the LLM. It works but is not scalable. Ideally, as a software developer, whether an individual or an organization, you want to provide documentation that LLMs can navigate by themselves.

You must also ensure that LLMs understand the software at a deep level to return the best possible code when developers ask them to. Unfortunately, according to Ionescu, “Most developer documentation or even user documentation is written for newbies, and that’s now a blocker.” Giving fast beginnings and basic code illustrations is fine for a person, but feeding such minimal data to a computer causes it to “struggle to provide serious, production-level code suggestions.”

Tiered documentation is designed such that “by default, crawling bots for LLMs get super-detailed, in-depth docs, and humans get friendlier docs,” according to Ionescu.

According to Ionescu, no one has done this before, but there is no reason it cannot be done. Delivering documents that please both people and robots will be difficult, but once procedures are established, developers will emerge as the ultimate winners.

According to O’Reilly’s Mike Loukides, LLMs are a long way from being able to generate code reliably and consistently enough to replace compilers. However, we now live in a world, where LLMs can help developers write amazing code. Improving documentation for developers and the LLMs on which they increasingly rely will be critical to boosting developer productivity.