The Ultimate Guide to Code Documentation for Development Teams

Documentation is all about making your code as usable as possible. The benefits of good documentation are many. Good documentation means it’s easier to…

• Onboard new developers to a project
• Track the status of ongoing development
• Continue work when a developer gets sick or leaves the company
• Share your work with a client’s development team

In this guide, we’ll look at the best practices for making documentation easier and less time-consuming for your dev team. We’ll also suggest protocols that your team should have in place to ensure development and documentation work together.

Documentation and Development Go Hand in Hand

Even though you might not think of it this way, every development project begins with documentation. Before a new project begins, the development team will meet to decide what they want to accomplish when building a new product/feature. This early objective for your project is actually the project’s first bit of documentation.

Traditional waterfall development would extend the documentation even further in this first meeting, planning out the entire project’s architecture. However, even agile development involves talking about, white boarding, and recording basic goals for where the project is headed. According to Fast Company, this first piece of documentation is one of the most important for getting your team on the same page.

Even if your company has separate development and documentation teams, this first meeting should involve people from both teams, and the documentation team should have access throughout the early development process. For example, at Mozilla they used a side-by-side tracking system for documentation and development. Mozilla has a documentation status page that lists all the features that have been built and which ones have docs written for them. They also use a bug flagging system so developers can point out areas that need updated documentation.

Even on a team where the developers write their own docs, these strategies from Mozilla are useful. They illustrate the importance of tracking, flagging, and using overall frameworks to make sure documentation keeps up with development.

Reduce the Need for Documentation in Your Code

One of the biggest strategies development teams can use to improve documentation is to reduce the need for documentation in the first place.

When your team is programming, have them pay attention to the way they’re naming variables, methods, classes, etc. The name should make it clear what the variable stands for or what the method does. When you use good naming, it makes your code readable itself, meaning developers new to the project can easily see what’s going on in the code just from the names you’ve used.

Here’s an example of self-documenting code.

It’s better to have names which you feel are too long, than names which are not 100% clear. I see the following block of code (or something similar) over and over:

for (int i = 0; i < books.length; i++) { … }

Everyone knows that “i” is usually the index of an array we are iterating over, so what’s the big deal? The issue here is when this block of code grows over the course of 10 years, and now this variable “i” is used across a 1000 lines of code.

A better variable name would be bookIndex:

for (int bookIndex = 0; bookIndex < books.length; i++) { … }

Making the code readable reduces the need for in-code documentation, explaining how things work. Clear naming eliminates the need to explain WHAT your code is doing. Now you’re free to use commenting to explain WHY and the intent behind your code.

Always ask yourself and your team: “Is this comment explaining what the code does (it shouldn’t if you’re using clear naming and structure) or why I wrote it?”

Consistently Use the Same Documentation Protocols and Management Tools

The next hurdle in code documentation for teams is setting up clear systems for documentation. Does your development team have protocols in place for how to write documentation? Do your developers know those protocols, have them memorized, and incorporate them into their workflows?

The key here is not to make things too complicated. The documentation process should make the developer’s job easier, not overwhelm them with more annoying work. Many conversations on developer forums around the web suggest that the easiest way to document coding patterns and other protocols you expect from your developers is through your project wiki or a simple markdown document contained within the repository. Since understanding new language features and code libraries are essential to understanding a project, it’s important to document these changes to the code base for your team members.

The other part of team protocols and coordination is the use of documentation tools. Some development teams have successfully implemented smart tools like Confluence. However, other teams have found that Confluence becomes bloated and scattered over time. Here’s how one Intertech consultant recommends keeping documentation in source control:

I always place as much documentation as possible in source control, right next to my code. This makes many people uncomfortable until they try it for a few months. All documentation generated by developers should live in source control.

I frequently hear “But my manager doesn’t use Git, how will they get the documentation?” If the audience of the code documentation is outside of the developers, add a build step to publish this documentation somewhere friendly to outside groups.

When documentation is part of source control, it becomes curated just like the source code. It is part of code reviews to keep is up to date and accurate. It is versioned with the source code, no more “Is this document for version X or Y”. If the document isn’t worth keeping in source control, it probably isn’t worth a developer writing.

Each development team will come up with its own solutions to the problem of how to create and track documentation. However, the key here is consistency across the team. Everyone working on the project should use the same processes for creating the docs. Ask the developers on your team how they like to document their code and what tools they prefer.

Write Your Documentation for the Next Developer

It’s common advice that you shouldn’t write documentation for yourself. Just because you understand how the code works doesn’t mean it’s self-explanatory. Instead, write documentation so that a developer with no familiarity with the project could understand what you’ve done and why.

At the same time, you’ll need to consider the end audience for your documentation: the next developer. You’re eventually going to pass your project onto someone else. Often a different technical team will be handling the product after you deliver it, and they’ll need to be able to understand what you’ve written, how it works, and why it was built the way it was.

The most important points to cover in your documentation for the next developer are:

1. The overall architecture of the project – What are the component parts of the software? How do they work together? Why did you build the project the way you did?
2. API references and other external connections – The large majority of problems with software have come from APIs. If you can clearly explain how your project hooks into existing data sources and (sometimes quirky) libraries, you’ll be prepared for many support requests ahead of time

The Challenge of Good Documentation

Code documentation is hard. It’s easy to write rules about what to document, and check off the box which says that the code is documented. It’s much harder to provide context to a problem, which is always available and accurate.  We hope this guide helps keep your docs useful and up-to-date.