I have drunk enough coffee and I will try to explain what I know.
TL; DR: write documentation to solve a specific problem for a specific group of people, not just to have the documentation.
First, you need to be good at writing. The author of Drunken Revelations has clearly denied this claim, but for most it may not work. You have to be able to take topics and find the main point, show the key details. These details need to be properly sequenced and then translated into clear sentences.
Good writing isn’t just about documentation, of course. You can test your ability in this area with any type of writing. Can you write how to find something in your home? Can you write a short speech? If you need to work in this area, I suggest you practice writing something other than documentation. Write blog posts, write short stories, write letters to friends, whatever. If you don’t read books regularly, start now. Your brain needs to be trained on a lot of well-written text before you can tell what works and what doesn’t in your particular case. Develop an editing skill that is very different from your writing skill (writing becomes easier if you trust your editing skills – you won’t filter yourself as much).
The most useful advice for writing documentation is to write in a conversational style. It is much easier to perceive information from informal text.
Okay, now back to the documentation.
There are different types of documentation, and people make ropes out of themselves, trying to get one kind of documentation to do the work of another. Stretching goes along two axes:
The training information containing practical steps is called a tutorial. If it does not contain any practical steps, this is an explanation. Both of these tend to be more suitable for beginners, so they should focus on explaining concepts and terms (and background information). In terms of explanations, it is really helpful to have a short summary at the top.
It’s safe to assume that, thanks to the information about when you are working, someone already has a general idea of what is going on.
The theoretical information used in the work is called the reference. This includes documentation for each method. Help documentation is a completely useless place to host a tutorial.
If this is not theory, then this guide. The guide is basically similar to a tutorial, with two important differences: it assumes some familiarity with the topic and the goal is to accomplish a specific task, not to teach. The checklist is a quick guide, but it can still be helpful if it’s very easy to forget about an important step. Use the guides when there are steps you need to repeat. They are especially valuable when the person doing the steps does not know how to complete the task (either someone on the other team, or you in a year).
Choose the type of documentation to write based on the needs of your reader. It may be that your code is actually pretty self-documenting, and reading the method signature really tells you what the method is doing. Excellent. This is for reference documentation. Now write the other three types.
If all you have is the reference documentation, the information will be a useless bunch of random facts for readers not familiar with the basics. Help documentation is like having a detailed description of intersections when new readers are looking for highway maps.
I think there is actually a fifth kind of documentation: breadcrumbs. These are small comments in code or notes in docs (or even error messages in custom linters) that point out to readers what they need to know. You can write a small comment with a link to the Jira ticket explaining why this code is needed, or you can tell people which command to run to fix the bug. Breadcrumbs are really easy to add to the docs and save tons of time.
Why
It is very easy to forget to write about things that seem obvious. Of course, how we create a microservice, I don’t need to write why we are doing this. But you need to.
This is obvious to you, but not to the reader. The reasoning behind the decisions seems really obvious to us because we’ve spent so much time thinking about it.
When you explain why you are doing something, you are forced to mentally trace the steps that led to the decision. It turns out it’s also a great way to introduce you to certain topics.
If you’re stuck trying to explain why, just imagine what the world would be like if what you are documenting suddenly disappeared. Who cares what they see?
It’s even better if you can explain the reason with a story. People are really good at processing and remembering stories.
I like the other comments in the documentation. For example. “We know this is not very good and we really want it to work like X, but it will require the T team to update their materials, and they are very overwhelmed, so we live with it for now.” It is the kind of information that brings everything together in people’s heads and makes them feel like they understand what’s going on.
Non-technical topics
Just because you’re documenting a technical topic doesn’t mean that the reader doesn’t need to know some non-technical things either. The reason this is the case is very serious.
Other useful non-technical details including:
- Processes to follow (for example, before you update something, send an email to this mailing list so support can get ready).
- Team dynamics. “That X team is really worried about Y happening, so ask them about Z.”
- Information about users. “We have a lot of users who have created their own pieces, and they don’t need to change their pieces, so we are making this update only for users without special pieces.”
- Interesting facts, for example “we call this system Narnia, because …”
Tutorials
The tutorials are meant to familiarize people with the topic. This is a really good way to do it, because people learn better when they do something, rather than just reading.
Tutorials also require a large investment (compared to other types of documents). Writing them probably only makes sense if a lot of people need to learn a topic. If it’s just a few people, meeting them face-to-face (or webcam to webcam) is probably the best use of time.
The trap when writing tutorials is trying to explain everything. Resist the urge to list all the technical details and all the exceptions to the established rules. You just want your readers to understand the basic mechanics. Small details can be left for documentation for more experienced people.
Also very often the tutorials just don’t work when someone tries to work with them. You need to try out the steps you wrote (ideally on a new computer without all the components already installed) to make sure they are complete and actually work. Then follow the steps the next time someone needs to use this guide and see where they get stuck.
The steps will also be outdated, so be sure to listen to people who have problems with them.
Guides
Guides tend to give a good return on investment. Spending 10 minutes listing the steps in a bulleted list can save you an hour thinking about what to do next.
This is especially valuable when it is difficult to understand what the steps are, or if an important step is easy to skip.
Write guides when you’ve just gone through the process and are motivated to avoid figuring it all out again.
Explanation and Help
To be honest, I’m not sure about the value of the javadoc style reference documentation. Of course, if a million people are going to use your lesson, roll up your sleeves and document everything down to the smallest detail. But if it’s just your team reading, they will already know 99% of what you can write.
Explanations are generally more useful, especially when they focus on explaining the reasons. If you explain the user and technical constraints that lead to the creation of a design, you can almost forget about explaining the design itself – armed with background information, someone can figure it out on their own by reading the code. You can (eventually) learn the structure just by reading the code, but it is difficult or even impossible to understand the reasons this way.
Practice of documentation
Writing documentation takes time. A lot of time. Spending this time on documentation isn’t just magic because someone says “we need more documentation.” You should set aside time for this and spend hours writing. No, this is not the most fun way to spend Thursday night, but you have to.
Or not? You should only write documentation when it is useful. You wouldn’t write code just to write more code (or maybe you would, but I wouldn’t). You write code to solve a specific problem. You should also write documentation to solve a specific problem.
This “something” can be implemented in order to help new people energize the team, reduce the bus factor in the team, avoid mistakes due to forgetting steps, save people time when performing actions, provide context, build an agreement, write down rude but important details, etc. If you don’t know why you are writing documentation, don’t do it. Once you know why, select the appropriate documentation for the problem being solved.
Please, in the name of all that is holy, don’t write documentation like this:
/**
* @param customer The customer
* @param order The order
* @return The price
*/
public Price getPrice(Customer customer, Order order) {}
This is pointless and teaches readers to mentally skip comments. They will skip comments that actually contain something useful. If you have nothing to say, don’t say it.
Documentation, like code, needs to be maintained. You have to pay for its storage. You must take the time to support it. Fortunately, this is usually much cheaper than maintaining the code. A few hours a month is all you need to read the entire wiki and fix what’s wrong right now.
Advice: create an “archive” section in your documentation and move obsolete materials there. It preserves the historical context, it is better than just deleting the documentation, and it does not need to be fooled by unsuspecting readers.
One way to save time is to turn other work into documentation. If you need to explain to a colleague how to integrate with your system, copy what you write in Slack into a document. If you wrote project documentation, copy several sections of it into the documentation and spend 10 minutes preparing it. Whenever you need to explain something to a reviewer in a code review, explain it with a comment in the code, not a commit on Github. Does your Jira ticket explain why the task needs to be completed? Cool, copy this and you have the documentation. (If not, get the questioner to write it!)
Tell people where to go to ask questions. To write “if you have any questions, you can contact us at # team-channel on Slack” in about 15 seconds. This can save you hours if you get confused. Pretty good payback in my opinion
So the coffee is running out, so I’ll stop at that.
