.png)
Software engineers need code documentation to succeed. You might know your code like the back of your hand now, but will you be able to say the same in a couple of months after working on more projects and writing more code?
To avoid the headache of wondering why you created the code the way you did, simply start documenting your processes. That way, you’ll always have access to the what and how of your projects.
The worst part is starting, so we’re bringing you five of the best practices for code documentation. If you implement these, you’ll be off to a great start!
Develop a Documentation Strategy First
Without a strategy, your code documentation will be all over the place, miss essential points, and, as a result, won’t exactly help the people reading it. In other words, it will only serve you.
Before you start, you have to know who your target audience is, what format you’re going to use, how many people will work on the documentation, and what takes priority, among other things.
For example, Flutter adds an interactive example section to their code documentation, letting readers test the code themselves.
Depending on your goal with the instructions, you can experiment with different formatting. If you believe it’s easier to show than tell, you can always make a quick video tutorial for the users, explaining what they need to hear.
The starting point of strategy development is also understanding the purpose of your documentation. Nathen Harvey, a developer advocate at Google, believes it is there to help the users achieve a goal.
He gives an example of software being down and users turning to documentation for answers.
In his opinion, the users need the files to contain a solution to the problem, in addition to being up to date, easily accessible, and accurate.
So, when you create documentation, think of the end-user who will have to solve a problem using it. Make it easy for the reader to understand the steps necessary to fix a problem.
When working on your documentation strategy, look at the big picture and figure out what you have to explain and the best way to deliver the data successfully.
When you plan it all and decide on the details of each file, the information itself will flow better, following your actual working process.
Divio helps users easily find an answer to their questions by offering how-to guides divided into sections and subsections that provide solutions.
Someone who uses their knowledge base to get help with building their Docker application will quickly understand what to do. You should do the same with your internal documentation. Since it must be helpful to the end-user, ensure that everything is well explained, even for someone inexperienced.
After all, your code documentation should be an explanation of the “why” behind the code. Readers should understand why they need the code and why it’s useful, so keep your guides descriptive, yet concise.
Once again, Divio does a great job describing their product without going into too many details, keeping things simple and to the point.
Strive to achieve the same level of clarity when explaining your processes step by step. The instructions must be aligned with the work processes.
A documentation audit will help you determine whether the same information appears in different places, possibly confusing users.
Keep Agile Practices in Mind
When writing code documentation, remember to keep it aligned with agile methodology.
If you use Agile project management, you already know you have to be ready for development arising from consultation with clients. In other words, your documentation needs to meet customer needs and goals quickly and continuously.
After all, in an agile environment, change is good since it often leads to long-term savings in both time and money. It would be wise to rely on the same principle when creating your documentation, and keep it concise and clear.
Your documents should serve as helpful instructions or solutions to a problem. If you go into too much detail, the explanations might end up being too extensive to be useful.
While traditional methodology expects you to plan and write down specifications in great detail at the beginning of a project, adopting this approach when dealing with user documentation will cost you a lot of time and energy.
Besides, updating such extensive documentation will be even more time-consuming.
On the other hand, you’ll spend less time on documenting if you offer relevant and clear instructions. Furthermore, it’s easier to change and update a more concise document, too, so you’re saving time from the get-go.
In his book Agile Modeling, Scott W. Ambler recommends keeping your documentation restricted to the data that’s less likely to change to avoid outdated information.
On top of that, Ambler stresses that agile documentation is geared towards a specific customer and their needs, meaning there’s no one size fits all.
So, keep your writing short, clear, accurate, and valuable. As for the style, it should be consistent throughout your documentation.
In a survey by Tom Johnson, over 76% of people who worked on developer documents said they used a style guide that defined the terminology and convention standards.
Another benefit of agile documentation is that it can be used in Scrum methodology, meaning your documentation will work great for 66% of companies that use this approach.
Since Scrum is also about learning as you go and gaining knowledge through the process, having excellent documentation as a starting point will work wonders.
Both Agile and Scrum rely on transparency and collaboration, which means sharing the documentation with all parties involved.
A cloud-based knowledge base is a great solution, especially if it allows you to share documents with people outside your organization, e.g., clients.
If you’re oriented towards customer satisfaction, being able to share the relevant documentation with customers is critical.
Allowing them to comment and collaborate in the files themselves is a bonus that specialized documentation software like Archbee offers.
Besides, it will be much easier to update and share the updates in real-time if you use a software documentation tool anyone with permission can access, thus saving you time and trouble.
Write for Humans First, Computers Second
When creating your documentation, remember that you’re writing it for actual people who will turn to it for solutions.
Even if you are the only one using your code now, another software engineer might need it later.
So, you should keep other people in mind when writing and try to make the content easy to understand for actual users, not just computers that will execute the code or search through the documentation to find what the users need.
The simplest way to cater your documents to users’ needs is to stick to the Divio Documentation Framework. For Divio, documentation isn’t one thing; it’s four.
They suggest using the following four types of instructions:
- Tutorials
- How-To Guides
- Explanation
- Reference
Each type is oriented towards a different purpose, be it learning, problem-solving, understanding, or information.
With these differences in mind, you can adapt your content to the needs of your audience.
With a good strategy and agile practices in place, you’ll know your readers well, making it easier to create documents that will help them specifically.
Next, think of the ease of access for your readers. They’re not computers, so they won’t be able to search through everything in your database easily, unless you use a Markdown-based system.
Markdown is a markup language that lets you use a plain text editor and format the text. According to Johnson's survey it’s also the most common source format in code documentation.
When you write documents using Markdown, the content stays searchable, meaning that a reader can use your internal search engine to look for a specific keyword or question.
The best part about it?
Our algorithm lets admins see what your users look up in your database. When you notice that a search word keeps repeating, you’ll know it’s time to update your documentation and better explain that specific section.
Another excellent editing tool that helps with reading is Mermaid, which lets you create simple diagrams. They are often better than writing for presenting detailed information, so use them to your benefit.
Software like Archbee lets you quickly switch to Mermaid options when writing, allowing you to create visualizations with complex sequences, flowcharts, and UML. This type of content is easily digestible, which is the goal of your documentation.
After all, you’re creating it to share your code with users, be it other developers or end-users.
The reader has to understand the why and how of your code, so use any code documentation tools you can to make the content readable and light.
Collaborate With Other Stakeholders
You can say you’re good at documenting your code when the customer is not the first person reading it.
They are the ones who should get the final product, which is complete, clear, and accurate code documentation that helps them use your software. If they get your first draft, your documentation process still needs work.
In his book Clean Code, Robert C. Martin mentions the software developer “Big” Dave Thomas, who explains that good code is something that other people can read, understand, and develop.
In other words, your code is not good if you’re the only one who gets it and can edit it.
Don’t forget that developers who get to read your code will get insights from it, which means you can turn code documentation into a learning moment.
If you’re trying to build a culture of knowledge sharing, asking people to review and comment on your work will improve collaboration.
After all, you want others to read your work, suggest what you could do differently to improve the code and offer alternatives. It’s better if your team spots an issue than if the customer does.
Technical writers should collaborate with engineers to ensure that the writing is excellent and accurate.
The easiest way to do this is by relying on scrum teams, consisting of five to nine team members who come together and share their expertise with one another in order to finish projects and deliver products.
For example, your engineers can collaborate with Quality Assurance (QA) testers.
In addition, another developer, teammate, and person working on the project will act as a fresh pair of eyes, letting you know exactly where you went wrong. They will point out things that are too detailed or, on the contrary, not explained well enough.
The Tom Johnson survey also found that most developers check their documentation using a code review tool.
Many of them turn to in-person meetings, collaborative annotation tools, and comments from users to improve their code. In contrast, only two respondents said nobody in their organizations reviews the documentation.
In other words, the overwhelming majority of developers do collaborate with other stakeholders and let them get a say in the documentation, which means you should follow in their footsteps and encourage others to read and review your code.
Dead Documentation Belongs in the Trash
Documentation is an endless work in progress.
For those who are good at writing and updating their documents, this isn’t exactly a problem. After all, you just have to keep improving it using the suggestions or ideas you get from your team or end-users.
Remember that your documentation only serves its purpose when it’s accurate and up-to-date. If it is only one of those things, that’s not enough.
For example, your documentation might be pristine, but written for the product’s older version, which renders it useless to new software users trying to find a solution.
At the same time, if you frequently update the information, but still have incorrect data floating around, does it help anyone?
A thing you can pay attention to is your customer’s feedback.
They’re the ones who use your documentation to solve a problem. When your end-users comment on your docs in need of more information, it’s a telltale sign you need to update it and add the missing data.
If you don’t keep agile practices in mind when writing documentation, you’ll find it difficult to update it, especially if you’ve just written huge chunks of text and have similar data repeating time and time again. So, keep future updates in mind when creating code.
This means, for example, not writing as many comments. Robert C. Martin explains that code constantly moves and shifts, but that comments often can’t follow, meaning you’re left with an out-of-place, redundant, confusing comment.
Martin explains that writers often over-explain in the code itself instead of letting the code do all the talking. He also gives a great example of a good vs. bad comment.
Martin also advises not to write comments that could become pointless. If you do write such a comment, you already know you’re going to have to update it or delete it later on, so why do it?
When you think your code no longer serves its original purpose or that there might be too much outdated information to update on time, simply delete it. Don’t be afraid of deleting something that could cause more harm than good to your end-users.
After all, as Martin puts it, outdated comments become “floating islands of irrelevance and misdirection” in the code that is supposed to be helpful.
Before conclusion, here are two read recommendation related to the our topic:
1. How to Write Code Documentation
2. What Makes Writing Code Documentation a Challenge
Conclusion
Your code documentation needs to be useful to end-users.
A great way to make it useful to your team as well is if you let them review and access your code. You’re also helping yourself that way, as you’ll get feedback that will help you improve the code.
Great documentation comes from a great strategy geared towards helping the end-users. With that in mind, follow these code documentation best practices outlined in this article and create impeccable code documentation that will help users and teammates alike!
