What is code documentation?
Code documentation is a collection of documents and code comments explaining how code works and how to use it. The form and size of documentation can vary. For example, some organizations provide code documentation in the form of an online knowledge base, in shared files containing annotated code snippets, or within code repositories.
Types of code documentation include:
- Internal code documentation—intended for developers inside the organization.
- External code documentation—intended for developers outside the organization who integrate with the product or need to understand its code.
- Low-level or inline documentation—resides within the source code and explains details of specific code parts in isolation, such as the purpose of certain functions and arguments.
- High-level documentation—describes the architecture, design principles, implementation guidelines, or other broader concerns.
- Walkthrough documentation—describes flows, patterns and other important parts of the codebase, especially for developers who need to contribute to the code.
This is part of an extensive series of guides about code documentation and software development.
Why you should document your code
Many developers don’t recognize the value of documenting code. They might argue that good code is self-explanatory. However, accurate documentation is essential for maintaining a codebase because it allows developers to quickly understand what the code does and how to work with it.
Also, while writing “clean and clear” code can make inline code comments redundant, because the code is understandable in isolation, it does not provide broader, more extensive insights into how the code works, why it was built the way it was, and how to make changes to it. This is especially true considering a flow that spans multiple files or even repositories. Making sure the code is clean simply does not tell the whole story.
Clear descriptions of your code are essential for collaboration across teams, specifically for onboarding new team members and sharing code with developers from other organizations, such as customers or partners. Code documentation is also important for the same developers who created the code, who might need to come back to it weeks, months, or years later.
Good documentation is especially needed when many developers use code inside or outside your organization. Taking the time to document the code will make their work easier, and they’ll appreciate it. Good documentation should save more time than you spend writing it—whether your own or the team’s time. In some cases, writing documentation can help identify overly complicated parts of the code and improve your architecture.
Related content: Read our guide to continuous integration documentation
Common types of documentation
Internal code documentation
Software engineers and developers write internal documentation for use within the organization. This type of documentation includes:
- Process documentation—provides high-level information, including product requirements and roadmaps for the development team and project manager. It can also include meeting notes and status reports.
- Developer documentation—provides details and instructions for developers and DevOps staff building, testing, deploying, or maintaining the software. It should provide technical information needed for day-to-day activities in a software project.
Examples for internal documentation include onboarding documents, design documents or inline documents.
Learn more in our detailed Guide to Coding Diagrams
External code documentation
External code documentation is intended for developers or other users outside the organization who need to understand and use a product’s code. A common example is API documentation for a product’s public-facing APIs.
Common types of external code documentation include:
- External developer documentation—provides basic instructions on how to use source code, integrate with a product, and leverage its developer-facing interfaces such as APIs and CLIs.
- Enterprise documentation—provides information for IT staff who need to deploy the software in the enterprise. It usually includes hardware requirements, sizing, operational requirements, and maintenance guidelines.
- Usage documentation—provides information for users who are not necessarily developers, as to how to use the product, without any programmatic interface. These documents may describe main functionalities within the product’s UI.
- Just-in-time documentation—provides developers with support documentation at the time they need it. For example, adding new documentation as a new feature is added in the form of a knowledge base article, FAQ page, or blog post.
Low-level / Inline documentation
Low-level documentation helps explain specific lines or blocks of code in isolation. Inline documentation does not explain how the line of code would work in a broader context or its role in a more complex architecture.
The most common type of low-level documentation is inline code comments. For example, a comment on a function declaration that describes what the function does, its parameters, and its return values. The comment describes a particular function in isolation, not the reason it is part of a specific flow.
Some developers don’t like writing comments but try to keep the code as readable and straightforward as possible. This is known as “self-documenting code” and can also be seen as a form of inline documentation.
Related content: Agile Documentation: Benefits and Best Practices
High-level documentation
While low-level documentation provides minute details of the code, high-level documentation tries to paint the overall picture. It might include the code architecture’s layout, underlying business logic, and the reasons for your decisions about the code. It might also describe different repositories or the main modules in a particular repository.
This documentation is useful when working with the codebase for the first time, but it doesn’t offer much more value. Software engineers rarely refer to high-level documentation because it doesn’t usually contain practical information for everyday tasks.
Both high and low-level documentation are insufficient on their own. Inline comments explain specific code areas without the broader context, while high-level documentation proves the bigger picture without the details needed to work with the code.
For example, you can describe general processes for extending Git source code in high-level documents—e.g., creating new git commands. However, you can only explain these processes properly by describing the details and providing real examples from your code. Adding these details means the documentation is no longer high-level.
Walkthrough documentation
Walkthrough documentation fills in the gaps left by low-level and high-level documentation by providing a guided tour of the product’s codebase.
It typically includes code snippets that explain points of interest on the product map as it moves from one landmark to another. It can point out recurring patterns and describe the interactions between code blocks that reside far from each other or in multiple repositories. Learn more in our article on InfoQ: The Renaissance of Code Documentation: Introducing Code Walkthrough.
Related content: Read our guide to coding diagrams
Code documentation challenges
Code is non-linear
Not all code follows a step-by-step paradigm, and the assembly order is not always clear when documenting code. Things that appear at the top, such as variables, may relate to the functionality at the bottom. Functions defined at the end of the code could be executed in another block of code in the middle. This becomes more complex as code flows span across multiple repositories.
The core paradigm for most technical writers is a task-based approach, where you start with steps 1, 2, and 3 and continue until the task is complete. However, this model is not usually possible with code documentation because the code can be inherently non-linear. You cannot start from the top and go down—you might have to move back and forth between multiple files and repos.
Audiences have different levels of expertise
Another common challenge is deciding what details to explain and which to skip. Some developers might have a certain technical background and might be highly familiar with a certain framework or pattern, while others are not.
When documenting your code, it is important to base the documentation writing on the knowledge and requirements of your target audience, even at very different skill levels. If your audience has wildly different needs and awareness levels, you risk covering too much for experienced developers with explicit explanations or skipping important information for newer developers.
The solution is to break the documentation into separate documents for different audiences or provide an incremental discovery model, where initial information is provided first, and users can click through or expand to additional information based on their information needs.
Code documentation requires knowledge of the programming language
Developers often create code documentation, but in many cases, technical writers are asked to help create this content. Technical writers are often unfamiliar with the specific programming languages used in the code they document. Even if they are familiar with some programming, it might not be the correct language for the specific project.
To work on code documentation, technical writers and editors might need to view tutorials to understand the basics of the project’s code. Developers need to be aware of this challenge and collaborate with technical writers to help them understand the code.
Code documentation requires maintenance
You must ensure that the code samples work with multiple versions. For example, if you tweak a code sample, you have to go back and update the entire code in additional to your explanations for each section to keep everything in sync.
Documents can be difficult to maintain from one release to another if the documentation contains many code samples. You need to check that the code works. You might keep your code separate from the narrative context to test it more regularly.
Code examples are not the only case where documentation may become outdated. Any time any process related to the code is described, the code may change thus making the document obsolete. This can be true for specific details (such as numeric values), or high level concepts (such as the software architecture or main flows).
Documentation might lack traceability
Oftentimes, it is difficult to find specific documents. The ability to track documentation throughout its lifecycle is essential for code management. Developers need to be able to see the documentation’s status at any given time—they must know if it has changed, been approved, or shared with other stakeholders. Traceability often requires a documentation management system.
Another issue is lost documentation—it’s not always possible to recreate lost files, or it might be time-consuming. Your organization should have a backup plan to ensure documentation remains available.
Code documentation best practices
Ensure your notes are accurate
When presenting ideas about code, start with general comments to draw attention to the most important details. You can describe things in more detail later, but short notes are enough to capture the main information without disrupting the flow of your document.
Consider what is the most salient information required by the reader—for example, definitions of important functions or arguments, processes or integrations that are important for understanding the code. Avoid long architecture or design discussions which are not required by the reader in the current context.
You don’t need to write complete sentences at this stage—focus on accurately capturing the context, useful URLs, and relevant code snippets. Use auto-save if available.
Use long-form descriptions to explain decisions
Ideally, you can handle this step during a break from coding (but before you move on entirely to something else). Everything should be fresh when explaining your ideas, decisions, and context.
Go through your short notes and expand on them with conversation-like writing. Describe what you did as if teaching others how to do it. You should cover the following topics:
- A strange-looking decision—explain why you chose to do something this way when you usually do something else.
- Challenges—what difficulties you faced and how to overcome them.
- Architecture—explain your decisions when making an architecture that supports your project objectives.
Long-form does not mean endless, so stick to the point. Write the documentation in complete sentences, as if you were explaining the project to another colleague, but keep it as concise as possible.
Incorporate prerequisite information
Don’t forget to include important prerequisite knowledge. You should ideally do this step when you have some distance from the project, but not too much. Best to always review the documentation you’ve written to be sure you have adequately filled in all the blanks. Even better, let a colleague read it and provide feedback before sharing it with the rest of the team.
Providing this knowledge is especially important if you use different tools and languages.
Leverage a code documentation tool
Code documentation solutions simplify the document writing and management process, making it easier and faster to create and distribute documents.
Some documentation tools allow you to publish documentation when complete and distribute it to your internal team or an external user. Some tools provide a version control system that enables teams to track changes over time. Some even make sure the documentation are always up-to-date.
Use Documentation as Code (DaC)
DaC is a way for developers to create and publish documents using the same tools and processes they use to write code. This idea has gained popularity in recent years, especially among tech companies. This process includes automatic link checking to ensure that the author’s changes are correct and deployment is safe.
Using a DaC approach allows technical writers to focus on writing and make it easy for readers to find useful accurate information.
Learn more in our detailed guide to code documentation best practices
Code documentation with Swimm
Swimm is a documentation platform built to deal with the main challenges of documentation for software engineering teams that want to create and manage internal documentation about their project.
Swimm’s core features include:
- DaC (Documentation as code)—Swimm documents are written in Markdown form and saved within the codebase.
- “Live” code—To make documents easier to write and richer, Swimm enables adding code snippets, diagrams, and tokens taken directly from the codebase.
- Automatic sync—Using a dedicated application, Swimm integrates into CI to locate and automatically correct documents that become stale as relevant code changes. Developers are prompted if code changes are significant and demand their attention.
- Enhanced discoverability—Swimm enables various ways to find documentation when needed. Its web application is used to structure documents using tags and Playlists and to search documents across repositories. Swimm also integrates with IDEs to highlight relevant docs next to code they relate to, enabling you to read them from the IDE without switching contexts.
See Additional Guides on Key Software Development Topics
Together with our content partners, we have authored in-depth guides on several other topics that can also be useful as you explore the world of software development.
Technical Documentation
Authored by Swimm
- How to create great technical documentation: ultimate guide
- Get started with technical documentation writing best practices
- Essential Resources for Technical Documentation Templates
CI/CD Pipeline
Authored by NetApp
- GitHub Actions Runners Using AWS and Cloud Volumes ONTAP
- Enhancing CI/CD Pipelines with Cloud Volumes ONTAP
- CI/CD Pipelines with Cloud Volumes ONTAP Case Studies
Connected Cars
Authored by EMQX
