BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage Articles Shifting to Continuous Documentation as a New Approach for Code Knowledge

Shifting to Continuous Documentation as a New Approach for Code Knowledge

This item in japanese

Bookmarks

Key Takeaways

  • The current status quo for sharing engineering knowledge within teams is broken. Code documentation requires new methods and tools to improve team efficiency and productivity.
  • Continuous Documentation is a new paradigm for creating and maintaining code documentation that involves incorporating it into the normal development workflow.
  • The principles of Continuous Documentation require that documentation be always up-to-date; be created at the most opportune time; and be tightly coupled with the code.
  • By practicing Continuous Documentation we can get high-quality documentation that actually works for developers, guiding them through the code base, while speeding up development and improving agility.

We continuously integrate. We continuously test and monitor. And perhaps, we also continuously deploy. So why do we suspend this essential continuity when it comes to documentation?

Developers deserve high-quality, up-to-date documentation - just like developers deserve a good keyboard, a widescreen monitor, coffee, and a quiet environment to work in. When a developer needs to build on, interact with, or change code someone else has written, they deserve documentation that will help them understand that code’s functionality, context, rationale, and more, without needing to reverse-engineer it, or waste time spelunking in threads and channels to find the people who might know.

But developers don’t get the documentation they need and deserve. And why is that? Because current documentation practices are fundamentally broken. The current state is much like the state of tests before the introduction of Continuous Integration. Developers approach documentation in concentrated sprints, documenting many things at once. Then the documentation gradually becomes stale, until someone can’t get their job done because it’s obsolete. This pattern is very similar to when developers implemented many unit tests at once, only to have many of them fall out of sync with the code (and fall out of relevance and usefulness) a few months later.

Given the current tools and practices, creating high-quality documentation simply takes too much time and effort. Then, making sure it is up-to-date as the code rapidly evolves is almost impossible. And if we can’t make sure the documentation is still valid, why bother creating it in the first place? We need another approach, which I call Continuous Documentation.

Why now? Lack of documentation is not a new problem; it’s probably as old as code itself.

  1. Because code is becoming more and more complex.
  2. Because developers are moving between projects, teams, and organizations more frequently than ever.
  3. Finally, because there are now tools that can solve this problem.

What are we aiming for with Continuous Documentation?

When applying Continuous Documentation, creating documentation is much easier, documentation always remains up-to-date, and it is more easily found or discovered when needed. It makes documentation something that not only every developer wants, but also something that makes sense investing in.

Continuous Documentation is the process that optimizes and reduces drift between the codebase and code-specific knowledge. Continuous Documentation applies the paradigm of automated integration of documentation into the development pipelines, by building and updating documentation incrementally, thereby keeping it in sync with the codebase.

Continuous Documentation doesn't just distribute the weight of documentation evenly so it doesn't mount up in a backlog, it actively speeds up the inner development loop - that is, the time from idea to actually pushing a change to the codebase.

The Principles of Continuous Documentation

Continuous Documentation means that the Documentation is

  • Always up-to-date
  • Created when best
  • Code-coupled

Always up-to-date

Continuously verifying documentation means making sure that the current state of the documentation matches the current state of the codebase, as the code evolves. In order to keep the docs in sync with the codebase, existing documentation needs to be checked against the current state of the code continuously and automatically. If the documentation diverges from the current state of the code, the documentation should be modified to reflect the updated state (automatically or manually). Continuously verifying documentation means that developers can trust their documentation and know that what’s written there is still relevant and valid, or at least get a clear indication that a certain part of it is no longer valid.

In this sense, Continuous Documentation is very much like continuous integration - it makes sure the documentation is always correct, similar to verifying that all the tests pass. This could be done on every commit, push, merge, or any other version control mechanism. Without it, keeping documentation up-to-date and accurate is extremely hard, and requires manual work that needs to be repeated regularly.

Note that a system that only alerts when the documentation doesn’t match the current state of the codebase would probably become a burden by itself, and is thus not likely to be adopted by developers. A good Continuous Documentation platform should aspire to update the documentation automatically, at least in most cases.

Created when best

Without Continuous Documentation, documentation is created on rare occasions, typically after an impacting event such as onboarding new hires, and usually when it is already too late. This leaves important parts of the code that only a few people know well.

Continuously creating documentation means that documentation is written not as an aftermath, but when it makes sense. For example, when a big feature has been completed, or when a crucial bug has been fixed in a way other contributors to the code would need to know or understand. This makes creating documentation much easier - developers write the documentation when everything is still fresh and clear in their minds.

Code-coupled

Code-coupled documentation means that it explicitly references parts of the code. That is, the documentation not only explains the code, but also contains or directs to parts of the code itself, so it is clear which source file and lines each document describes. These can be snippets of code, names of functions, values, or any other parts of the code.

Comments in the code (also known as “inline documentation”), are a form of code-coupled documentation, provided they are updated when the code that they refer to changes. However, comments can only describe the specific lines that are near them and are therefore extremely limited. Writing easily understandable code can also, arguably, be described as code-coupled documentation, but it is limited in what it can explain. Interactions between parts of the code, processes, flows of data, and other aspects can not be clarified by code comments or by well-written code. Continuous documentation tools should couple rationale, experimentation, and other hard-earned knowledge that doesn’t fit well into code comments.

High-level documentation, such as architectural documents, are code-coupled, only if they specifically and explicitly refer to or include parts of the code. Usually that is not the case, given that their purpose is to give a high-level description.

What does it enable?

Writing documentation that is actually practical for developers - when the documentation actually contains parts from code, can really explain how things are done in the codebase, and why - not just in a high-level perspective. It can take the reader through the journey of the code across various files, classes, and perhaps multiple repositories. In that way, the documentation can walk the reader through the code, as if they were getting a first-hand explanation from the person who had written the code originally. Its practicality could also mean that it gives a developer a step-by-step manual for processes and changes that are repeated often.

Coupling documentation with the code enables us to ensure that it is up-to-date, as we know what code parts relate to which document. Further, it allows us to measure documentation coverage - that is, which parts of the code are already covered by documentation, and which parts are not. This allows us to know where we should focus our efforts when creating new documentation.

Coupling also improves the discoverability of documentation. Even if high-quality and up-to-date documentation exists, it is meaningless if it is not consumed, especially when it is needed. Building up knowledge means making it accessible. Having documentation that is highly coupled with the code, allows one to find the relevant documentation just in time. For example, an engineer may be reading code in a specific file, and then have a reference from the specific code section to the relevant documents describing it.

Summary

Developers deserve practical, high-quality, up-to-date documentation that allows them to quickly understand code they are not familiar with. Documentation of this sort speeds up development and allows agility for dev teams, as developers can quickly shift between various tasks.

Yet the process of creating high-quality documentation and keeping it up-to-date is so expensive in terms of time and effort that it just doesn’t make practical sense to the people that need to create it. We must change the way we create and consume documentation, and follow the principles of Continuous Documentation: creating code-coupled documentation in tandem with fresh ideas and ensuring it is up to date.

Hopefully, this approach will inspire you to rethink the way your team, and developers in general, share knowledge with each other. The way in which we share knowledge about code must change, and we can start by implementing small steps in the right direction in our teams, if we follow the principles described here. When Continuous Documentation is widely adopted, it will enable agility within dev teams in a way that is hard to imagine. Given the right tools, following this approach should become a no-brainer. Developers deserve Continuous Documentation.

About the Author

Omer Rosenbaum is the CTO and co-founder of Swimm, the company that syncs teams with code. Omer founded the Check Point Security Academy and was the Cyber Security Lead at ITC, an educational organization that trains talented professionals to develop careers in technology.

Rate this Article

Adoption
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • BDD

    by Roland Heimdahl,

  • BDD

    by Roland Heimdahl,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    How does this compares to BDD and suits of human-readable-tests/documentation (run by cucumber for example)? I started to think about Specification by Example by Gojko Adzic when reading the article, is this in the same area?

  • Re: BDD

    by Omer Rosenbaum,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Thank you for your reply @Roland!
    Specifying with tests is beneficial and provides clarity to a program's functionality. If the tests are well defined and implemented continuously - then this approach indeed applies with the principles described here.
    Yet, tests do not cover the whole story. Tests cover what the current implementation does, and not the decisions that have led to the current implementation. Neither do they explain the other implementation possibilities that the developer decided not to cover.
    In addition, tests have another role (in addition to providing clarity/documentation) - which is, well, to test the functionality. Thus there are usually a LOT of tests when one strives to really cover all the cases, which may lead to a major cognitive load. In other words, if I want to really understand a part of the codebase, I'd rather get a clear explanation of the main flow and its motivation, rather than lots of tests covering some edge-cases which may be important to understand, but not at my current state.
    In other words, there is indeed a connection between tests (and specification) and documentation, but I believe it's only a partial overlap.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT