Technical Documentation in the Gen AI Era: A Paradigm Shift
Intro about me
Hi, My name is Nicolas Marcantonio. I am a Software Engineer from Argentina, worked in companies such as Mercado Libre and Google, and now starting my own company named Autonoma. I am curious about how to make software engineering easier for all devs like me, who like coding and not losing time.
Documentation Challenge
In this post I would like to tackle one specific task that I always felt was a necessary evil: Code Documentation. We really need it but it is very expensive to create and maintain.
I’m tired of the constant scenario of having to rely on team sessions, pair programming, or reading the entire repository to understand a new company or project’s system. This method doesn’t scale, it’s not very efficient, and how quickly we can start contributing depends on the experience of the developers involved.
Navigating through legacy code adds another layer of complexity. Understanding outdated or poorly documented codebases can be a real challenge.
Last but not least, integration with external APIs or SDKs requires clear documentation. Without it, developers face obstacles, causing delays and errors. Proper documentation ensures smooth integration, minimizing future problems.
Now let’s focus on the other half. Why is it expensive you may ask? We as devs continuously have work to be done, either for sprint features, bug fixing, technical debt, backlog, etc. In this context, documentation is placed on a lower priority level than sprint features and bug fixing, falling somewhere between technical debt and backlog.
As we always start new sprints with new tasks, we are almost never able to finish documentation, and that’s why it is always outdated or lacking. Therefore entering a loop with no end.
Research mode on
As we’re well aware, these days companies lean on user-friendly wikis like Confluence and Notion for their documentation needs. These platforms are fantastic for collaborative teamwork and knowledge sharing, but let’s face it, they are really time consuming.
As I explored possible solutions, I realised that incorporating Generative AI (A.K.A. LLM’s) could make a significant difference. Mainly because I was working the whole day on gen ai projects at google.
I began my research and quickly found some straightforward solutions, focusing primarily on what I refer to as atomic documentation. These solutions take one code file as input and generate text explaining the code as output. No structure, difficult to scale.
Imagine an average repo with +500 files, making those docs manually and storing them in Confluence.
There are other solutions in the market that use AI for wiki-like documentation. However, most of these solutions concentrate solely on atomic documentation, creating individual pieces of content without a holistic approach.
An alternative approach to addressing the challenges posed by legacy code is directly migrating the existing codebase into a different technology stack. This method involves converting the codebase, often written in outdated languages or frameworks, into a modern and more efficient stack.
While this is a good solution, it comes with its own set of complexities. Translating legacy code requires a deep understanding of both the original and target technologies to ensure a seamless transition.
It involves planning, lots of testing, and debugging to resolve compatibility issues and optimise performance. High level documentation can significantly ease the process of this migration.
Currently working on
After all this research process, in Autonoma we decided to give it a try on a root solution for this challenge. We are building high level documentation using Gen AI. We integrate directly with your versioning control system, and build your documentation with no human in the loop.
If you would like to give it a try, here is our demo. We are always looking for cool repositories to document, so if you have one in mind please contact us!
You can also email me at nico@autonoma.app for any thoughts and feedback.
