From the AI Native Dev: AI-Powered Documentation: Insights with Omer Rosenbaum, CTO of Swimm

Introduction

In a recent podcast episode, Simon Maple sat down with Omer Rosenbaum, the CTO and co-founder of Swimm, to discuss the evolving landscape of documentation in software development. With a background rooted in cybersecurity, Omer provides unique insights into the challenges and solutions surrounding code documentation. This blog post delves into their discussion, exploring the importance of documentation, the role of AI, and how Swimm is revolutionizing the way developers interact with their code bases.

From Cybersecurity to AI and Documentation

Omer Rosenbaum's journey began in the cybersecurity domain, where he worked in various roles. His transition to focusing on AI and documentation was driven by the recurring challenge he observed: new developers struggling to understand existing code bases. "I found that engineers, even with the best training available, when they first got onto their job in software organizations, they were new to the code base and it would be a very hard first month to get acquainted with the code base and how things work at this specific company," Omer explained.

This challenge of onboarding new developers highlighted a broader issue of knowledge sharing within organizations. As Omer noted, "When the organization grows and the code base grows, there are parts of it that no one who is actively on the team has written themselves."

Defining Documentation

The conversation then shifted to defining what documentation means in the context of software development. Simon Maple emphasized that documentation can mean different things to different people. Omer categorized documentation into several types:

• Readme files: These are often markdown files that provide an overview of how to get started with a repository.
• Client-facing documentation: This usually includes API documentation, detailing how to call the API and the parameters involved.
• Wiki-style documents: These are a mix of high-level explanations, diagrams, and architectural overviews. However, Omer pointed out that these documents tend to become outdated quickly.

Omer stressed that documentation should not just be about having documentation for the sake of it. "People don't write documentation to have documentation, they write it to share their knowledge, right? For others to read and understand," he said.

The Challenges of Keeping Documentation Up-to-Date

One of the biggest challenges in maintaining documentation is keeping it up-to-date as the code evolves. Omer explained why this is a persistent issue: "The docs are decoupled from the code. As a developer, I'm in the zone, I write my feature, I test it, I debug it, I ship it. I don't know that it actually affected some document someone else has written some time ago."

He identified three main issues:

1. Difficulty in writing documentation: Most developers find it hard to write good documentation.
2. Inevitability of becoming outdated: Developers often feel it's futile to write documentation that will soon become obsolete.
3. Finding the documentation: Even if the documentation exists and is up-to-date, finding it when needed can be a challenge.

How AI Can Assist

AI has the potential to address these challenges in multiple ways. "AI can help you write the documentation in various ways... AI can help you keep the documentation up to date as the code changes, and AI can help you find the documentation when you need it," Omer elaborated.

One of the key features of Swimm is its ability to couple parts of the code with corresponding documentation and track changes. This ensures that the documentation evolves with the code. Omer emphasized the importance of human input in some cases: "Sometimes you made a change, and no AI, no matter how good, can know why. This is something we need to extract from the human brain."

Swimm's Approach to Documentation

Swimm aims to streamline the documentation process by leveraging static analysis and AI. Omer explained the origin of the company's name: "We were told that the way to get people onboarded to a code base or get to know new parts of the code base is by throwing them into the water, into the deep end of the pool, then they either sink or Swimm."

Swimm generates documentation automatically based on the code base and static analysis. It also allows developers to write documentation that is kept up-to-date as the code evolves. The goal is to minimize the time developers spend on documentation while maximizing its utility.

The Role of Static Analysis and AI

Swimm relies heavily on static analysis to create accurate documentation. Omer explained the balance between static analysis and AI: "We heavily rely on static analysis, especially for creating documentation... AI is great at some things, outstanding at some things, not at everything."

Static analysis helps in understanding the code structure and flow, while AI translates this into natural language. This combination ensures that the documentation is both accurate and easily understandable.

The Impact of AI on Developer Workflow

AI and tools like Swimm can significantly impact developer workflow by integrating seamlessly into their existing processes. Most developers prefer to consume information in their IDEs with minimal interruption. However, from an organizational perspective, it's crucial to ensure that all documentation is up-to-date, which can be enforced through pull request processes.

Omer highlighted the importance of balancing developer preferences with organizational needs: "We don't want to enforce developers to use a specific IDE or a very specific workflow, but at the organizational level, you do want to make sure all the documentation is up-to-date."

Automatic Documentation for Legacy Code

Legacy code bases present a unique challenge as they often lack proper documentation. Swimm addresses this by automating the documentation process. Omer explained, "We analyze the code base... then we decide what's important to document at the first step."

By providing an initial high-level overview and allowing developers to dive deeper into specific modules, Swimm ensures that even legacy code is well-documented. Developers can generate more documents on the fly or ask questions using a chat interface, where AI can provide additional context.

The Future of Documentation with AI

As AI continues to evolve, its role in documentation will become even more significant. Omer believes that AI will play a crucial role in project documentation, especially as developers become more disconnected from the code they write. "AI assistants can rely on documentation to generate better code or to answer questions in a better way," he said.

Omer also emphasized the importance of maintaining up-to-date documentation: "Outdated documentation that's taken into account as the source of truth can be misleading, and it's really hard for AI to differentiate."

Summary

The podcast discussion with Omer Rosenbaum highlighted the critical role of documentation in software development and how AI can assist in making it more efficient and accurate. Key takeaways include:

• Documentation is crucial for knowledge sharing and onboarding new developers.
• Keeping documentation up-to-date is a significant challenge due to its decoupling from the code.
• AI can assist in writing, updating, and finding documentation.
• Swimm combines static analysis and AI to automate documentation processes.
• The future of documentation will see a shift towards project-level documentation as AI-generated code becomes more prevalent.

As the landscape of software development continues to evolve, tools like Swimm will play a pivotal role in ensuring that documentation remains a valuable resource for developers and AI assistants alike.