We’ve all worked with technologies where the documentation is poorly written, outdated, or completely nonexistant. This always sucks, and it’s a huge time and energy drain.
Imagine trying to learn Java or C# without any documentation or textbooks. Alternatively, imagine trying to learn Angular or Bootstrap without documentation. Unless you have direct access to the people who created these languages and frameworks, you’re going to have an impossible time.
The reality is that software is often only as good as its documentation. The technologies mentioned above are all very powerful, but only because they have strong documentation that allows people to use them effectively.
Yet most of us overlook the importance of documentation in our own work. This ends up causing a lot of inefficiency and wasted time. But as the savvy engineer might recognize, it also offers an opportunity for him to differentiate himself from his peers.
Here I will discuss some effective techniques to help write solid, quality documentation.
How you will benefit
Proper documentation offers you the following advantages:
1. Save Time And Frustration
Our brains are not suited for long term storage; they are better at calculating and reasoning. During your work, there will be times where you need to work in part of the codebase that you haven’t looked at in awhile. There will also be times where you encounter a problem that you’ve seen before.
Without documentation, you will have no way of recollecting all of the necessary little details. This results in you spending unnecessary time and effort trying to update the code or solve the problem again.
Conversely, if you had written the documentation you can spend a few minutes to load all of the details back into your brain before continuing with the task at hand. So documentation has the power to save you huge amounts of time and emotional energy.
2. Improve Your Communication Skills
Documenting your work forces you to think very hard about how you communicate. It’s usually quite difficult to write with clarity, especially when you’re writing about a technical subject. Often, things that are clear in our minds can be difficult to explain. So as you work hard to write well, you will become better at communicating your thoughts and ideas with clarity.
This translates to speaking better. That’s because writing trains your mind to formulate thoughts more quickly and easily. While writing documentation will likely improve your writing the most, your communication in general will improve, making it even more valuable.
3. Learn Your Technologies Better
When you start documenting your work, you’re effectively trying to teach something to someone. In the teaching role, you’ll quickly identify a number of gaps in your knowledge. So you’ll go out and do some research to gain a better understanding of the relevant technologies. That’s because you know that your documentation will suck if you don’t fill the gaps.
Who benefits from this? Anyone who reads the documentation will benefit, but you’ll certainly benefit the most from the additional knowledge.
4. Gain Recognition for Your Work
Most engineers are uninterested in documenting their work, so they either don’t do it or they don’t do it very well. This means that when you write good documentation that helps other people, you’ll be recognized for it. It might even encourage other people to document their work better.
All of these things make you a happier and more productive engineer. Being more productive makes you more valuable. Being more valuable opens up more opportunities for you.
Let’s look at what to do.
Make time for documentation
If you don’t allocate time for documentation, it’s not going to get done. So the first step to doing all this is to actually give yourself the necessary time. Don’t let it be an afterthought when estimating your work.
Give yourself 1-2 hours per week for documenting your work, but monitor and adjust based on whether you need more or less time.
It should not be difficult to justify this time to management. If they seem skeptical, simply inform them of the bus factor.
Ensure it’s timestamped and editable
Whatever software you choose to use for documentation purposes, make sure that each of your documents are timestamped and editable by all team members.
By keeping your documents timestamped, people will know if what they’re reading might be out of date. Ideally you won’t have any outdated material, but in reality there are things that get stale. The timestamp will help to mitigate the harm that this stale material can cause.
Editable documents are mandatory because everyone on the team should be able to correct mistakes, remove outdated content, and add new material. Documentation is not a task for only one person. Ideally, your software will also track a page’s history as it changes. This allows you to revert to old versions whenever necessary.
A good example of a software that has these qualities is Confluence.
Say only what you need to say. People who are reading your documentation have a limited amount of time and are trying to get something done. Make it easy for them by getting to the point.
If you are documenting your application’s architecture, don’t go into the nitty gritty details. If you are documenting a specific component, don’t talk about all the other components in your system.
A corollary to this is that you must maintain your documentation. Something that was once useful might not be anymore. When you’re working on a garden, you don’t just water the flowers – you continually rip out the weeds before they get too large and obfuscate the beauty. The same applies to your documentation.
Document your work immediately
The proper time to write documentation is immediately after you’ve solved the problem or made the code changes. The reason is simple: this is the time when you still have all of the relevant details in your head. If you wait until later, you will have lost some of the context, which means your documentation will also have lost some context.
As mentioned in the section above, make sure you don’t document anything unnecesary. If you’ve made a non-trival code change, the question you need to answer is: “What are the relevant details someone needs to pick up where I’ve left off?” If you solved a problem, the question is, “What steps did I need to take in order to fix the problem?”
The answers to the questions above are what go in your documentation.
Keep things organized
If your documents aren’t organized, nobody is going to be able to find what they’re looking for. And the harder it is to find something, the less likely people are going to waste time searching for it. If you don’t keep your documentation organized, you might as well not write it at all.
Don’t worry my friend, a simple structure will prevent this from being a problem. There’s 2 main things you need to do to keep a simple structure:
1. Don’t Use More than One Nested Folder
Nested folders are usually a pain in the ass to deal with. They make it hard to navigate around the documentation hierarchy to find what you’re looking for. So you want to avoid nesting folders as much as possible.
With that said, there’s definitely some cases where a nested folder makes the most organizational sense. Try your best to create your documents so that they can be logically organized without nesting. If you can’t find a way, that’s probably a case where a nested folder makes the most sense.
2. Organize Your Pages in a Consistent Way
The first point is about your overall documentation structure. This one is about how you organize your individual pages. You want to try to organize each of your pages similar to the other ones. This will make it easier for people to find what they’re looking for within the page they’re on.
For example, when you’re documenting each architectural component in your application, you might have the following sections in each of the pages:
- Architectual Diagram
Following these 2 things will make it easy for people to find the specific document they’re looking for, and also the specific section of that document too.
Focus on the “hows”
People don’t usually read documentation for theoretical knowledge. They read it because they have a task that they need to get done. They might be trying to solve a specific problem, deploy something to an environment, or use a software component. Give them what they want:
- Show how to solve a problem, not why the problem is showing up.
- Show how to deploy the software, not why it’s deployed that way.
With that said, there are certainly cases where you’ll want to explain the why. If a problem shows up frequently enough, you’ll want to set aside time to resolve its root cause instead of just putting a BandAid on it every time it comes up. Understanding the why will be important for addressing the root cause.
Have a starting point for beginners
A “Beginner’s Guide” will be a valuable section of your documentation for onboarding new teammates. The value of this is pretty intuitive: it helps to ramp up new teammates faster and it allows them to learn more about your application on their own time.
Unlike the rest of your documentation which is likely to be reference material, this section should be written such that it has a clear start and end, and a nice flow from start to finish.
A lot of software has this type of thing. Most of Microsoft’s Azure offerings such as Cosmos DB have quickstarts and tutorials. Jasmine has a section called Getting Started. You’ll find them everywhere, and that’s because they’re valuable.
Have a troubleshooting guide
A troubleshooting guide will certainly be one of the most valuable parts of your documentation. If you don’t yet have any documentation, building this out first will perhaps bring you the greatest value.
This should be the place where you document common issues and problems in your application and how you resolved them. It’s quite common for issues to not be a one-time thing, so if build this guide then you will quickly and easily resolve issues when they show up again.
More importantly, your team will be able to utilize it to solve a problem that you’ve already solved (or vice versa). Both you and your team will be grateful for not having to spend more time looking at a problem than necessary.
As much as possible, you want to make sure the troubleshooting guide gives specific solutions to specific problems. People will not be reading this for theory; they will be reading it because they have something specific they’re trying to resolve. So this is not the place for abstraction.
Finally, it’s more important to explain the how than the why here. If you had to choose one, choose the how. Again, these problems are typically an impediment to the task at hand, so the most important thing is usually to remove that roadblock.
You don’t have to take my word for the value of a troubleshooting section. Look to AngularJs and Amazon’s AWS for examples of this. These are just two examples of software that have troubleshooting guides. There are many more. And they’re all doing it because it’s a time and stress saver.
Let’s conclude with a checklist of the items discussed above:
- Have I allocated time for documenting my work?
- Do the pages in my documentation have “last-modified” dates so people know if it might be outdated?
- Is everyone on the team able to edit the documents?
- Have I documented only the relevant details?
- Have I avoided nesting folders as much as possible to keep the organization simple?
- Is each document organized in roughly the same way as the others?
- Have I focused on the “hows”?
- Is there a Beginner’s Guide for new teammates to familiarize themselves with the application?
- Is there a Troubleshooting Guide where people can see if an issue they’re having has already been resolved?