Let’s be honest—it’s not always that software documentation matches production environments, let alone that documentation exists at all. Too often, developers are pushed to deliver code faster and faster, and documentation often falls under the wayside as a second priority. As such, obscure functions and code libraries often become undocumented and difficult for new developers to comprehend.
Generative AI is having an impact on many areas within the software development life cycle. And documentation is another surefire area that artificial intelligence is set to revolutionize. By running large language models (LLMs) over preexisting codebases, AI could document legacy technologies and potentially even generate documentation in lockstep with new projects.
Many obstacles inhibit documentation practices across modern engineering environments. Below, we’ll check in with the experts to see how AI could advance the status quo. We’ll consider some techniques for using generative AI for documentation, outline the potential benefits and discuss some of the caveats to watch out for.
The Blockers to Current Documentation Practices
Various obstacles within the software development pipeline can hinder a documentation-driven culture. A significant roadblock, until recently, has been upkeeping documentation manually.
“It is almost impossible for organizations to keep the current state of their IT application portfolio documented manually,” said Miten Marfatia, founder and CEO, EvolveWare. Newer agile documentation generation tools can fix this by creating and updating metadata for IT applications automatically, yet they still require some manual intervention, he explained.
In addition to manual documentation standards, other inhibitors can present themselves, such as balancing support for pre-existing documentation for old projects with documentation for new projects. “There is an eternal tradeoff between creating documentation for new features and revising or optimizing documentation for existing features,” explained Sanjay Sarathy, vice president, marketing, Cloudinary. “As companies add more products or existing products become richer, the tradeoff calculus becomes more complex and harder to get right.”
According to Igor Jablokov, CEO and founder of Pryon, organizations suffer from a lack of knowledge visibility, which can hinder development and even become a compounded risk within a highly regulated industry. “Friction abounds—it takes so much effort to document things, and tribal knowledge of all types is seldom properly recorded,” he said. “So, at times, organizations have to restart projects because they don’t know how an existing component works.”
Streamlining Documentation With Generative AI
As one can see, there are many drawbacks to the current state of documentation habits. However, generative AI is set to greatly advance the current manual and error-prone documentation standards. It could help address documentation policies for projects that have been sitting in the queue for too long while also encouraging new developer experiences to emerge.
“With generative AI modeling techniques, the documentation process would become progressively seamless and automated whether an application is being documented for the first time or its documentation is being updated,” said Marfatia. “Generative AI will best apply to documentation and transformation of legacy code.”
“Generative AI can certainly be used to streamline documentation processes,” said Sarathy. “It’s particularly promising and valuable in that it can help accelerate the process of keeping legacy content fresh and accurate.”
While it might not replace manual reviews entirely, generative AI could be used to flag old content, update code samples and help address gaps in the full scope of documentation support, said Sarathy. He likens this to the 80/20 rule: AI can help teams optimize high-trafficked pages while keeping up with the other 80% lower-priority applications.
Last but not least, generative AI presents a new opportunity to create novel experiences with old documentation, bringing some new life back to how projects are shared and understood. “By transforming previous static documents into interactive experiences, an organization can discover contradictions, gaps, and overlapping content,” said Jablokov. “They can unify multimodal assets from audio, images, text and videos that may contain critical regulatory information or lessons learned.”
Techniques for Using AI For Documentation
First and foremost, generative AI is set to benefit the documentation and transformation of legacy code the most since large volumes of data and code are already available for the model to ingest to infer understanding of similar code. So, it might behoove adopters to first trial AI-generated documentation in this scenario.
But what would the actual process look like? Well, speaking generically, it would first involve training an LLM on a large data corpus, which will likely include an enterprise’s software development artifacts like code, documentation, functional specifications, technical specifications, test cases, user stories and a variety of other supporting materials, explained Keith Cox, managing director of application modernization & migration at Deloitte. “Generative AI can be used to utilize foundational knowledge for generating future state system artifacts,” he said. “We can use these foundational legacy elements to create high-value LLMs for the enterprise.”
With this in hand, developers could prototype a desired functionality. But taking this a step further, if generative AI was used to generate a data model, it could also help spur design-first approaches for greenfield development. “Ultimately, generative AI could revolutionize the entire development life cycle,” said Cox, “First by accelerating the generation of design specifications and then potentially for some application scenarios, replacing the end-to-end cycle of application development.”
Yet, for generative documentation to be effective, it will rely on a valuable data corpus and bespoke capabilities that extend beyond off-the-shelf models. “The highest value generative AI models will be those that are specialized with large amounts of samples, targeted to specific industries, market segments or applications of technology,” said Cox.
Benefits of Using AI For Documentation
Generative AI is set to improve documentation and, in effect, speed up future development. LLMs that generate the documentation for legacy applications could be useful for generating functionality requirements for modern applications, too, said Marfatia. Ultimately, generative AI could revolutionize the entire development lifecycle.
In addition to development efficiency gains, the end benefits to the business could easily be improved user experiences that result in higher revenue and profitability. “The content produced by the brand can be updated more regularly to ensure greater accuracy and thoroughness,” said Sarathy. “Better, more accurate content leads to fewer support tickets and faster resolutions.”
Another interesting outcome of adopting AI for documentation generation is helping teams contend with multiple cloud providers and an increasingly diverse array of technology stacks.
“Instead of bouncing between myriad provider sites to support their internal development teams, they could unify all support documentation within a singular experience,” said Jablokov. “This allows them to reduce the risk of errant signals when they interact with the public web, as well as see underperforming vendors in a coordinated way. As a bonus, they could blend in their own internal documentation, so they have a cohesive view of what technologies are used for what workflows.”
That said, AI-driven documentation generation (and all generative AI endeavors, for that matter) should be undertaken cautiously, especially when it comes to the security concerns of the organization and not ingesting intellectual property without permission, said Marfatia.
Final Thoughts
It’s good to document your code—not only for learnability but for security reasons, too. By encouraging a more regular, automated regiment for documentation, technical leaders could enhance service discoverability, reduce zombie endpoints, increase the reusability of internal services, enable partner-sharing capabilities and reap other benefits.
Generative AI presents an interesting opportunity to localize and document preexisting shadow IT, making it more visible to engineers. And it could guide the documentation of greenfield development too. Yet, of course, these models rely on a large data corpus and take effort to implement. As such, generative AI shouldn’t be trumpeted as the end-all cure for every scenario or software development woe.
