3 code documentation examples and lessons learned

What is code documentation?

Documenting code is writing and maintaining documentation for a software application’s source code.

Code documentation examples include comments within the code, external documentation such as user manuals, technical specifications, design documents, and internal documents like coding guidelines, standards, and conventions.

The purpose of code documentation is to provide information about a codebase to developers currently working on the project, helping them understand and improve it. It also guides users and other technical professionals (e.g., DevOps engineers, security analysts) who may need to work with the code in the future.

This is a part of a series about code documentation.

Why should you document your code?

Let’s look at why code documentation is necessary. Clear code documentation does the following:

• Streamlines onboarding for new team members. Code documentation bridges the gap so people can get up to speed quickly and contribute more quickly. Accurate and up-to-date information describing the codebase helps developers quickly understand the code they’re working with and its history.
• Makes collaboration across teams much more efficient. When done properly, code documentation will save you and your team a lot of time looking for information or trying to find why things work the way they do.
• Makes it easier and safer to share code with partners, customers, and developers from other organizations. Code is non-linear and complex. Aspects like the constructed order of code and data flows are not always clear when reading through a codebase.

Example 1: writing internal code documentation

Internal code documentation is intended for developers inside your organization. Common types of internal code documentation include process documentation and developer documentation.

• Process documentation provides developers and project managers high-level information like product requirements, roadmaps, meeting notes, and status reports.
• Developer documentation provides internal developers and DevOps engineers with detailed instructions for building, testing, deploying, and maintaining software.

Internal documentation can include design documents, architecture diagrams, class and method definitions, or onboarding documents. A common internal code documentation example is UX design documentation, shown below from UI prep, which covers user personas, user story maps, user scenarios, and a UX style guide.

Lessons learned:

• Use internal code documentation for people inside your organization to help them understand processes and technical information.
• Write internal code documentation for stakeholders across a variety of roles. Be sure to include as much technical and non-technical information as possible to be meaningful for the reader.
• Internal code documentation may contain privileged or sensitive information that you wouldn’t otherwise release to the public, so double-check that the docs are protected from the public and provide a disclaimer to internal readers to prevent them from sharing.

Example 2: writing external code documentation

External code documentation is intended for users, customers, and developers outside your organization who both use the software and integrate with the product and need to understand its code.

Common external code documentation examples include:

• External developer documentation (like API references or open source project README files).
• Usage documentation (like user manuals, installation, or troubleshooting guides) – created for users who may or may not be developers. This documentation should show how to use the software and describe the main functionalities within the UI.
• User guides – a form of external documentation meant to help end-users troubleshoot common issues, see visual demonstrations, and receive simplified technical information they can easily understand.
• Enterprise code documentation – created for IT staff who need to deploy the software in an enterprise organization. Typically, this documentation will include operational and hardware requirements, sizing, and maintenance guidelines.

Below is a code documentation example of user docs from the Google Workspace Learning Center for the professional version of Gmail.

Lessons learned:

• Use external code documentation for people outside your organization to help them use and extend code-based projects, products, and services.
• Ensure external code documentation is appropriately written for external users. Make it available for existing users, potential future users, and anyone with an interest or dependency on the code
• Do not include sensitive or proprietary information in your external docs. Even if the docs are “gated” or protected in some way, they are still external and used by people outside your organization

Example 3: writing walkthrough documentation

Walkthrough code documentation describes flows, patterns, and other critical or complex parts of the codebase. It bridges the gaps left by low-level and high-level code documentation, and provides a guided tour of a software’s codebase, usually including code snippets to explain important points on a product roadmap.

Walkthrough documentation can save countless hours for scaling organizations, giving details about recurring patterns and describing interactions between parts of the code.

The code documentation example below is meant to show a recurring pattern by walking the user through multiple areas of code related to a single instance of this patternn. In this case, the pattern is adding a command to the CLI, and the examplified instance is the command `clone`. Notice that the document consists of snippets from various files, taking the reader on a journey along the logical flow of the code.

Lessons learned:

• Use walkthrough documentation to help people understand flows, patterns, and complex parts of your codebase.
• Walkthrough documentation can be internal or external (e.g. open source), so ensure the documentation discloses the appropriate information for the intended audience.
• Write walkthrough documentation as if you were talking to someone and guiding them through a codebase in a face-to-face meeting.

Code documentation using Swimm

Swimm is a premier knowledge management and documentation tool for code with robust features designed to help teams manage the challenges of creating and maintaining internal and external docs for their software projects.

All code documentation created with Swimm is written in Markdown form and saved within the codebase, making it convenient for devs to write and manage during the development process. Swimm provides the ability to add code snippets, diagrams, and tokens taken directly from the code base, adding depth to your docs without additional effort. Save your team time and mental energy by providing various ways to find code documentation when you need it and access docs in your IDE to avoid context switching during their workflow.

Get started with Swimm today!