Code documentation is notoriously difficult to write, which is why technical writers and developers often avoid this task.
Nevertheless, even the best software needs to be extensively documented to facilitate the work of developers building it and enhance the experience of the people who use it.
In this article, we’re talking about the challenges of documenting code and offering some possible solutions to make it easier to write as well as consume.
The first challenge lies in the very nature of code and the fact that it isn’t written primarily for humans.
Code Is Not Linear
Most technical writing is, at its core, sequential. It describes procedures and provides instructions in chronological order, from one step to the next.
That’s because the intended reader of this kind of writing needs to replicate those steps so that they can achieve a desired result.
Here’s a quick example from a troubleshooting guide for connectivity issues in the communication app Slack:
As you can see, the solution to the issue unfolds in chronological steps, which makes it easy for the reader to comprehend and apply them.
Code documentation is different. Code is written to be understood primarily by machines, meaning it doesn’t have to be written in a linear way.
Tom Johnson, a top expert in the technical writing field, sums up the problem rather well:
Code itself is non-linear. What appears at the top (e.g., variables) might not be implemented until functions at the bottom. Functions defined at the bottom might be run inside other code blocks in the middle, and so on. When you’re given a chunk of code to document, its assembly order isn’t apparent at all.
So, how do you explain or describe (document) non-linear code to a reader who needs the explanation to be delivered linearly to understand it?
Unfortunately, there’s no straightforward answer. Writers have to get creative and possibly employ some UI devices to help the reader connect their writing to the correct code segment.
Stripe uses an interesting approach here. In Stripe’s documentation, clicking on a particular step in a procedure will highlight both the textual explanation and the section of the code it refers to.
So, for instance, the second step in the following document (“Define a product to sell”) refers to lines 18-22 in the code.
To sum up, text intended for humans follows a different logic than code, in that the former needs to be presented in a linear way, while the other doesn’t.
This is something of a challenge for the technical writer documenting the code, but this challenge can be overcome with some creativity and a clever UI element.
The Need to Know Programming Languages
Technical writers cannot be expected to adequately document code if they don’t understand it. And this extends beyond just being able to read multiple programming languages.
They also need to be knowledgeable enough to explain to the developers reading the documentation what the code does and how it’s implemented.
This presents a challenge because technical writers don’t always come from a technical background.
In fact, according to data gathered by Zippia, most of them come into the field with a degree in English, business, communication, or some other non-technical field.
Technical writers documenting code need to be proficient communicators as well as technology enthusiasts, and that’s a difficult combination to come by.
However, there’s a silver lining here.
Since good writers proficient in code are rare, technical writers who invest their time in learning one or preferably multiple programming languages stand to significantly advance their careers.
Best of all, learning to code has never been easier, thanks to online learning platforms such as Udemy and Codecademy, which allow aspiring developers and technical writers to progress at their own pace and from the comfort of their own homes.
Here's a blog post about best practices in code documentation for software engineers you should follow.
So, for anyone who wants to upgrade their career and work as a technical writer who can competently document code, it’s a good idea to take up learning some programming languages.
According to Stack Overflow, these are the most popular ones:
So, if you think about it, the need to know programming languages is an opportunity as well as a challenge when it comes to documenting code.
Writers who invest in learning the basics of coding will never struggle to find work.
Code Documentation Needs to Be Updated
The unique thing about software, games, and other code-based products is that they keep evolving and changing long after launch.
And as the product changes, so must the documentation that explains its code.
This is quite different from other forms of technical writing, where documentation, once written, doesn’t need to be updated in any way.
Take a manual for a washing machine, for example.
The product it serves is a piece of hardware that’s always going to be used the same way, meaning this type of documentation can even work in a printed format.
However, a technical writer documenting code needs to stay on top of the changes made to the product so that they can update the documentation along with it.
This means that, in addition to being excellent communicators with a working knowledge of coding, these technical writers need to be organized and detail-oriented so that no change is implemented without an update to the documentation.
And these updates can happen multiple times a month, which means extra work for technical writers who already have their hands full.
For example, have a look at how the code documentation for Salesforce’s Lightning Web Components has changed in the late months of 2023:
As with any type of technical documentation, code documentation is completely useless if it’s not accurate.
In this case, that means that every change to the code requires the documentation to be updated, providing additional challenges.
Developers Have Different Skill Levels
Technical writers documenting code often have a very generic target audience to write for: developers.
This might seem pretty straightforward, but it’s actually quite problematic because developers consuming this kind of documentation have wildly different skill levels.
The challenge this presents is writing documentation that’s easy enough for junior programmers to understand and use but not so basic that they bore more experienced developers who don’t need everything spelled out for them.
Unfortunately, this is another challenge that doesn’t have a simple solution since documentation can’t be two things simultaneously.
There are some strategies for approaching this issue, though.
The first one is opting to over-explain the code.
After all, risking the boredom of senior developers should be preferable to leaving less experienced developers completely in the dark and unable to do their work effectively.
So, take the time to explain the basic terms and show the reader how to do the simplest actions with the code.
Coding newbies will definitely appreciate it, while seniors are free to skip the basics.
Your other option is to present the documentation without additional explanations to avoid wasting the reader’s time but to embed links into the text that will take the reader who needs more information to a separate page where they can find it.
A technical writer needs to find ways to document code accessible to developers of all skill levels.
This can be challenging, but the key is to provide access to every valuable bit of information, even if that means transporting the reader to a different resource.
Documentation Needs to Be Organized
The last challenge in writing code documentation actually stems from some of the other problems we’ve discussed in this article.
As we’ve seen in the first section, code and text are often written side by side in this type of documentation, meaning it would be impossible to write it using regular text editing software (such as Word or Google Docs, for example).
We also mentioned that code documentation needs to be updated along with the product in order to stay accurate and relevant to the software.
In that case, it needs to be structured in a way that enables users to efficiently track their documents and find them easily when they need to verify or change them.
In other words, code documentation needs to be neatly organized to prevent inaccuracies and information loss and facilitate easy consumption on the part of the reader and management on the part of the writer.
To tackle this problem, technical writers use advanced software documentation that has features that make writing, publishing, and managing code documentation a more manageable and enjoyable task.
For example, Archbee boasts a powerful multi-language code editor that enables writers to input live code into their documents as easily as they do text.
Alternatively, Archbee can be integrated with other products and platforms, like GitHub, for example.
That makes it possible to document the code in GitHub and sync it with Archbee to create neat, shippable documentation.
This kind of software has other features that help you stay on top of your documentation. The one that’s very relevant with regard to the organization is document verification.
Archbee’s version of this feature allows you to set up automated alerts that let you know that some time has passed since the document was last updated and that it needs to be verified for accuracy.
Source: Archbee on YouTube
Just choose the person you want to carry out the verification (or modification if the document needs an update) and set the verification cycle, and you’ll never have an outdated code document again.
So yes, code documentation needs a bit more organization than regular technical writing. But this challenge is easily overcome with the right code documentation tools at your disposal.
Conclusion
In this article, we examined the five aspects of documenting code challenge that make it so difficult to write.
Some of these challenges stem from how programming languages work, while others arise from the specific skills and tools needed to write it.
We also offered some tips that can help you overcome these challenges and write code documentation with speed, skill, and accuracy.
In the end, we’ve proven that, where code documentation is concerned, every problem really does have a solution.
