Best Tools for Automatic Technical Product Documentation

Technical documentation is essential for product (and team) success, but creating and maintaining it is not one of the fun parts of the job. Here are the tools I’ve found the most useful over the years

The Documentation Challenge

Before diving into tools, let’s quickly cover the challenges of software docs:

• Code changes faster than devs can update docs
• Different versions of docs are needed depending on the audience
• Docs live in a silo, separate from code, product docs, sales context, etc.
• Finding what you need to update everything either requires a human with a ton of context, a bunch of humans, or lots of searching

Now, what tools can we use to help?

Top Tools for Automatic Technical Documentation

1. gjalla - Context-Aware Architecture Documentation

gjalla is the first tool I’ve used that generates documentation straight from the codebase. It saves me personally at least 10 hours a month when I’m coming up to speed on a new codebase or documenting/updating docs for an existing one.

Key features:

• Automatically generates system architecture diagrams (including architecture, data flow, and sequence diagrams) from a codebase
• Diagrams are interactive and editable on a canvas
• Easily adapts to different levels of technical detail, so non-technical stakeholders can understand the system
• Has an integrated q&a feature that generates answers using a combination of text and visuals
• Architecture reviews on pull requests
• Service cost overview (not as related to docs, but because it can see the whole system it can provide a single pane of glass for software ops which is something most teams don’t have)

Best for: Teams who need a source of truth about how their system works, automatic documentation from codebases, and answers for sales enablement.

2. Mermaid

Mermaid is a tool that allows you to create diagrams from text. Engineers love it because it allows them to create diagrams using code.

Key features:

• Diagrams can be version controlled alongside code
• Has an online playground so you can see and edit the diagram as you iterate
• Well adopted in the developer community

I struggle with Mermaid at time because you can’t control how it lays out the diagram, and for complex systems they often end up unreadable. Additionally, even though it can be version controlled, you still have to create it manually.

Best for: Developer-focused teams who prefer to maintain documentation close to their code.

3. Lucidchart

Lucidchart is a tool that allows you to create diagrams in a visual canvas. Before finding gjalla, Lucidchart was my go-to. I much prefer the canvas approach because I’m often making docs to explain complex systems, so its super important to lay it out in a way that is intuitive.

Key features:

• Visual canvas with many different shapes
• Can be embedded into other tools like Confluence
• Support for different types of diagrams, including swimlanes, sequence diagrams, architecture diagrams, etc.

Lucidchart can be good for brainstorming since it has so many bells and whistles and you can experiment a lot. But once again you have to create all your collateral manually which can be a pain.

Best for: Teams who need many different shapes and specific features, and will need to experiment with different layouts.

4. Other tools

There are a handful of other tools, but most can only be used by developers. Although this can be awesome when you’re writing code, I haven’t found many that continue to be helpful the moment I’m collaborating with a non-engineer.

Best Practices for Automating Documentation

• Consider tools that are suitable for different types of stakeholders. The more that documentation can be easy to understand and available in a self-serve way, the less overhead and frustration the team will have across the board.
• Consider tools that fit seamlessly into your existing workflow.
• Consider tools that support how you want your organization to be operating over the next 5 years, not just a quick solution for today.

ROI of Automatic Documentation

I’ve personally saved so much time and frustration by finding tools that fit into my workflow. Here’s how you can quantify the ROI of automatic documentation for you and your team:

• Reduced time spent manually creating docs - Often 70+% less time spent creating and updating docs (for compliance, product marketing, architecture reviews, etc.)
• Revenue acceleration because GTM teams don’t have to wait on bespoke docs being manually created for every prospect
• Increased velocity on product teams because everyone starts with shared, up-to-date context
• Faster onboarding for new team members who can see the picture of the system from day 1

Conclusion

Docs that explain how a software system works are essential for teams that want to move fast and deliver value to their customers. Creating good docs takes time and energy, so its essential to find the right tool to support your team today and how you want to operate into the future.