Why Documentation Matters

Software is still eating the world, and there’s no end in sight.

Large parts of our civilization depend on critical systems, from power grids to aviation, from the financial system to healthcare. The world is running on code. There are still countless large corporations and institutions that require more custom software to be built. The physical world is increasingly controlled with software, from public transit to autonomous vehicles. The rise of AI is already creating more software across the board.

Writing code and building systems creates knowledge. If not captured in time, this context decays rapidly. To maintain the existing infrastructure, it is crucial to understand why decisions were made and what it takes to keep the systems running. We can’t afford to rewrite large parts of our stacks. We can’t afford to lose any context.

Documentation is the single best investment toward building a sustainable engineering organization for the long run. While code explains what the system is doing and how it’s done, documentation explains the why.

Great documentation empowers teams to get more work done while avoiding expensive mistakes. It

1. unblocks engineers, especially in distributed and remote teams
2. simplifies and shortens time spent on code reviews
3. ensures anyone can pick up any task, if longtime engineers leave the team
4. shortens onboarding times and creates a repeatable onboarding experience both for new hires and engineers switching teams
5. provides past decisions for future reference and prevents going in circles
6. improves clear thinking and raises code quality
7. helps educate the team to grow their skills and perform better

These benefits alone should make it clear to anyone that proper documentation is not only nice to have but critical in the long run.

Unfortunately, teams have been held back by subpar tooling.

1. Products and digital services are constantly evolving based on customer needs. Because of that, documentation can no longer be written once ahead of time but must move in lockstep with the product.
2. Documenting requires context switches, which creates too much friction. Writing docs is too frustrating and time-consuming to be enjoyed by engineers.
3. It’s often hard to find documentation across a fragmented landscape of tools — engineers spend up to an hour each day searching for knowledge.
4. It’s easy to forget to update documentation, especially if you don’t know what’s documented already.
5. Teams don’t own their docs and cannot ensure their intellectual property remains private.

We believe that these obstacles must be overcome in order for most teams to invest more resources into their documentation efforts.

Any approach to solving the current issues around documentation must provide two things:

1. A radically better user experience: Writing and maintaining documentation must be frictionless. No context switches, no more outdated documentation. Instant AI-powered documentation search. Integrations with issue trackers and internal wikis.
2. Trust: Teams must have full ownership of their documentation, providers must guarantee data sovereignty and prevent usage in training ML models unless explicitly agreed upon.

Introducing CodeTrail

Today, we’re introducing CodeTrail, a new product and company focused on building a radically new documentation experience and the only open-source solution to engineering documentation.

At the heart of CodeTrail is the idea of documentation close to code. Engineers document their codebase, describe higher-level architecture, track decisions, add details for the code review, and much more without ever leaving their IDE of choice by using the plugins for VisualStudio Code or IntelliJ-based editors.

Workflows like onboarding and code review are simplified by annotating the codebase, giving useful hints to new engineers and reviewers alike. We have seen onboarding and code review times reduced by more than 50% in some cases.

CodeTrail is designed to support first-class AI features to unblock engineers by finding documentation and answering any question. With CodeTrail AI, engineers save up to an hour each day and get to work on what really matters.

CodeTrail stores documentation as plain old Markdown right in your Git repositories. This ensures full ownership and compatibility with existing tools. It also allows incremental adoption with no added overhead or risk.

For trust and flexibility, we are open sourcing the documentation experience at the core of CodeTrail and offer self-hosted options of our cloud services for small teams to large enterprises.

The team

As a founding team with almost 20 years of combined industry experience, we care deeply about getting engineering teams to do the best work of their careers.

Bruno has spent the past 8 years working in high-growth teams and experiencing the bottlenecks of growth and engineering productivity. He brings a pragmatic and high-velocity approach to building a best-in-class product and company to the table.

Tim has a relentless drive to build the best possible product. Combined with deep understanding of data protection and privacy laws and regulations, he ensures both the product and company are built for the long run.

Our roadmap

We are currently building and testing our open-source IDE extensions with pilot customers in an early preview.

The system already helps engineering teams to write documentation much faster and without friction. Documentation is stored in the Git repository and teams can adopt CodeTrail incrementally with zero risks.

We are planning to release the product for general availability in the coming weeks.

Upcoming features include CI integrations for GitHub Actions and other providers for ensuring documentation freshness, improvements to the documentation experience, integration with other tools like knowledge-base systems (Notion and Confluence), issue trackers (Linear and Jira), team messengers (Slack and Teams), and more.

We are committed to fixing engineering documentation for the next era of computing. Ultimately, we want to support any company building software with capturing and accessing critical knowledge and context.

If you’re working on a team building software and want to help everyone work better, share more knowledge, and reduce risks in the long run, I’d love to discuss how CodeTrail can help your team. If this sounds interesting, get in touch for a personalized demo!