It’s the job developers traditionally have hated: code documentation.
Here’s why it has to be done.
The what and the why of technical documentation
Starting with a basic, working definition of technical documentation: all materials explaining the development and use of a software application.
So, why is technical documentation so important?
Good documentation explains not only what the code does, but also how it does it. Without documentation:
- It will be more difficult for someone else to pick up your code and work on it later. Plus onboarding new team members becomes a laborious process. Fixing bugs without any context/documentation; just not ideal.
- It will be difficult (though probably not impossible) for you to pick up your code and work on it later. Think about how many projects you will have worked on and how much code you will have written 3 or 6 or 12 months down the road. How could you possibly remember what you were thinking when you wrote the code you finished today?
So, even though it might be not your first choice to write your documentation today, it will be much more difficult down the road if you don’t.
This is part of a series of articles about technical documentation.
Top 10 tips for technical documentation writing
With that in mind, here’s our top 10 list of documentation tips that will help get you started.
1 – Just write it!
You’ve just written code that adds a much-requested feature to your company’s application. It’s time to finish the job by documenting it, but you’ve got 20 items in the backlog…
Your mind will never be as clear about what you’ve done as it is right now. Each day that goes by will make it harder for you to remember what you’ve done and why you did it that way. Save yourself the time and hassle, and just write it now. And, of course, there’s no need to finish a feature before you begin writing. Do it a step at a time, and you’ll be glad you did.
The “fresh in your mind” version from today will give you the strongest framework to build on.
Write it now. Refine it later. Done is better than perfect.
2 – Write your technical documentation with a new dev in mind
Given the ever-moving nature of the high-tech industry, there’s a better than average chance that the next person to work on your code won’t be you. You will have moved on to a higher-profile project, and a new dev will come in to work with your old team. Or maybe your company has brought on a remote team to help keep up with growth.
So, write your code documentation with a new dev in mind.
The purpose of your internal technical documentation is to make your code more understandable. When deciding what to include, just keep that in mind.
3 – Keep code documentation simple
There’s no need to explain every line of code. Document what would you need explained if you were picking up this code to work on it for the first time.
Write in short sentences and keep explanations concise and straightforward. We don’t mean that you shouldn’t write advanced technical code documentation. On the contrary, it’s the elements that aren’t so straightforward that need the best explanations.
4 – Add references and code
Context is everything. Add code snippets (with markup language), libraries, API endpoints, parameters, coding conventions, and additional references to your explanations.
Referencing other sections of the documentation or code instead of repeating them makes your documentation easier to update. But maintaining these references makes it harder to keep your documentation up to date as the code changes. This is where Swimm’s documentation tool makes all the difference – automatically detecting and marking where your document is out of sync with your code)
5 – Add a quick start option
When onboarding a new team member to work with your code, you want to get them up to speed quickly, but you don’t have time to sit over their shoulder stepping them through the documentation. This is where a comprehensive collection of related resources can be invaluable.
Give your dev team quick start page or bullet points that link to all the relevant resources.
The benefits:
- It significantly improves the user experience for your reader
- Provides context by giving them a high-level overview of the documentation
- Allows them to easily return to related resources when it’s time to review them
- Makes the content easier to consume by breaking into chunks
To create a more sequenced and organized learning experience for new developers, take a look at Swimm Playlists, which allow you to group numerous types of related resources in a single location for your readers to work through in the order you choose. Swimm also has created documentation templates as a quick start option to help you get started.
6 – Help readers find the documentation
Be sure to keep technical documentation in a centralized (preferably cloud-based) location, organized into logical folders or buckets. If you’re using Word documents, PDFs, or Google Docs, ensure that you give viewing rights to the people who need to access them.
Of course, if you use Swimm’s documentation platform, you’ll find docs when you need them in your IDE and access them right next to the code they refer to.
If nobody can find or access your documentation, it begs the question as to the point of writing it in the first place.
7 – Document code changes
Document any changes to your code. Be sure to include new features, bug fixes, deprecated/sunset features. The documentation should explain the why: why the code changes and you should write down whatever it is that you and your dev team will want to remember next time.
Documentation will help keep your codebase free of spaghetti code and dreaded technical debt.
8 – Get documentation feedback
Even if you don’t have an “official” review workflow, share your documentation with your team and get their feedback.
A second set of eyes will help you recognize that what may be crystal clear to you might be not clear at all for another developer.
9 – Create an updating plan
If you already have some documentation debt, it’s time to jump in and get free of it. But the prospect can seem overwhelming.
Fortunately, there are documentation strategies to help you get moving in the right direction, along with Swimm’s platform for facilitating ongoing documentation that’s always up to date.
10 – Make documentation as easy on yourself as possible
Documentation and automation fully integrated into your workflow – honestly, that’s how to make it easier on yourself. Edit docs that are coupled with your code, and auto-synced.
Related content: read our guide on technical documentation templates.
Bottom line
Responsibly maintained documentation has real financial consequences when it comes to developer onboarding, code maintenance, and the accumulation of technical debt. But implementing best practices in code documentation is not only possible, it’s a complete game changer and you’ll never look back.
Check out Swimm’s demo to see how Continuous Documentation can become a part of your team’s workflow and lead to effective onboarding of new developers.
