Writing Effective Documentation
There's a common scenario I've encountered while onboarding with different companies. I sit down with my shiny new laptop, get my editor and iTerm installed, go to the README and start trying to get the code up and running — only to find out their docs are nonexistent, incomplete, or worse, completely wrong.
Documentation is an important part of any codebase, but it feels like it's always getting left behind. It makes sense why - it takes time to write them and keep them properly maintained, and most coders would prefer to, well, code. This might be fine if you're programming a project for yourself. But if anyone else is going to be working on the code or trying to use your program, it's important to write clear, easy-to-understand documentation.
Writing effective documentation takes planning and effort. In this post, I'll go through some planning steps and what I think makes for good documentation.
Before You Start
Before writing documentation, there's a number of questions you need to ask yourself so you have a clear idea of how to format your writing. Answering these questions will help you understand your intended audience, the purpose of your project, and how to best document its use.
Who am I writing for?
Before I do any kind of writing, I think about who I am writing for. For example, I am writing this blog post for anyone interested in writing technical documentation for software. Since it's a blog post, I know I can write in a more informal tone than I might use for an article or paper. I know my audience will be English-speakers since the post is written in English, but they may not speak English as a first language - so I need to be aware that any idioms I use or references I make may be confusing to some.
Some examples of groups that might be reading your documentation are:
- Seasoned programmers who will work on the code
- New programmers who will work on the code
- Programmers who currently work on the code
- Programmers who will work on the code 10 years from now
- Product, design, or business people looking to understand more about what your code/software does or how it works
- Users of the code/software
- You 5 years from now trying to figure out why in the world your designed your code this way
You might be writing for one of or more of those groups. If you don't understand your audience, you can't write as effectively for them. For example, if you made a recipe app for a grandparent who knows nothing about coding, your documentation wouldn't go into detail about the architecture of the program - you would only need to explain how they should use it.
I'll criticize a past article I wrote as an example. I wrote about testing with RSpec previously for PragmaCoders. I used Pokemon as an example since I thought it would be a fun and clear way to demonstrate what I was talking about. But there are some assumptions I made about my audience that may not be entirely true. I had to assume that:
- My audience knows what Pokemon is.
- They understand the basics of the game, like the fact Pokemon have a type and moves.
- Not knowing either of these things would not be a distraction or make my examples unclear.
It's not an example I would use in the documentation for a company, but it's an example I felt okay using at the time for an informal format like a blog post. But it's possible that's something I'll want to rewrite to make it more accessible for more people — and it's something to think about for future posts.
So be sure to nail down your target audience before you start writing, so you don't need to rewrite as much down the road.
What does this project do?
This is a question you're going to need to answer for your audience - it might seem obvious to you what your program does, but that might not be clear to others. What problem are you solving by building this? Answering this gives useful context to your readers and they can keep it in mind as they learn more.
Why does this project exist?
This kind of goes with the last question, but there might be reasons beyond its obvious usefulness. Did you need to create this to make another piece of the codebase work? Or did the business decide this needed to be made? Is it an open source project solving a problem you encounter a lot? Or is it a better version of something that exists? Again, this is more context that can help your reader understand what they should be getting out of this program.
How do I use it?
Writing the Docs
Now that you have a good idea of the purpose your documentation is serving, it's time to write the dang thing. So, let's look at what makes up good documentation.
Write Clear Code
The easiest way to start with documentation is to write code that is easy to read. If a programmer can jump in and understand what a function does because you named it well, that's a great start. If you focus on writing good, clean code you don't have to worry about documenting every little thing about the program, such as how your functions work. For example, if you have a
Report class that has a function called
printReport, your user can probably figure out that it prints the report. This means also following conventions for the language you're in, such as using
snake_case where appropriate for naming.
Make It Easy to Skim
It will be more useful to your users if you make your documentation skimmable, so they can easily find the answers they need. Using something like a table of contents can help them quickly find the section they need if they have a quick question.
Using links throughout your documentation can also help the user find all of the context they need to understand your program. It can be links to outside documentation for libraries the user may need to install, or references to other topics in your own documentation. It also allows you to reference more complicated topics that come later, without having to take time to explain them right then. Try to stick to one topic at a time, and use links to make any references you need to related topics.
Another thing to consider is using consistent terminology. If a user wants to quickly search the document for keywords, they need to be able to assume that you won't change the terms and names you use for certain concepts. For example, if you have a component called an "alert", you don't want to later call it a "notification" — it not only makes your component harder to use, but it makes it harder to find references to it in the docs.
Assuming you wrote easy-to-understand code, you shouldn't have to worry about writing out what your functions do. It may only be necessary to discuss the overall architecture of the program and how pieces fit together. However, while we'd all like our code to be completely self-explanatory and our architecture to make perfect sense, it doesn't always work out that way when you're writing code for someone other than yourself. Sometimes if we work in the corporate world, we have to deviate from set patterns or do weird, hacky things to get a quick fix out. Or sometimes the business makes decisions that make our code more complicated than we'd like. Just remember to document these times. Try to write down why you made the decisions you did and the context surrounding them. Even if you couldn't write perfect code at the time, it will help future developers if they know what you were trying to do and why.
Other decisions you'll want to make note of are any kind of file organization or naming conventions you're using. It can be things like how you name colors, how names determined by marketing map to classes in the code, etc. If there's any kind of standards set by the team or the business itself, you'll want to outline those clearly.
I love documentation with plenty of examples. It lets the reader more easily jump right into coding if they want to. Sometimes I like to just play around with something for a while, then go back and figure out the details of how it works. For me, it makes the process of learning a new tool or framework much more fun and exciting if I can jump right in.
It helps if your examples follow any naming conventions you've set up, so try to code them as if you were really using them. That also means testing them to make sure they actually do what you say they do.
Also, examples don't just have to be code. Anything that can make your software easier to understand will help. Code examples probably won't be necessary if you're writing more of a how-to for end users. In cases like that, it may be more appropriate to use screenshots to guide them through the program. If you're writing for other coders and the codebase is pretty large, diagrams of how everything fits together might be useful as well.
DRY doesn't necessarily have to apply to documentation. Sometimes repetition can help users better understand what you're trying to say. Don't be afraid to repeat yourself if you think it's necessary to help readers understand a concept. It's possible they won't understand something until they see it in a new context and repetition can help with that process. Try not to overdo it of course, but if you think repeating a concept once or twice could help, don't be afraid to.
Keeping it Updated
If we're counting clean code as part of the documentation process, let's also count the documentation as part of the code. You do not want outdated documentation - it is incredibly confusing and frustrating to jump into a project that has docs that are out of date or just completely wrong. If you change part of your code, think about any documentation you need to update. If you use code reviews, have developers review your code and documentation changes.
Edit and Review
Once you've written your documentation, you need to edit it. Definitely check for spelling and grammatical errors, as well as any confusing phrasing. You can run it through something like Grammarly for free just as a quick check.
But the main focus needs to be the clarity of the docs. If you're writing for other programmers who might edit the code, have a peer look over it. If you're writing it more for the business side, see if someone in that area can read it and ask them if they found anything confusing. Get as many eyes on it from your target audience that you can.
Writing good documentation can take time and effort, but it's worth it in the long run. With just a little planning, organization, and work, you can have beautiful docs that make your project look more professional and easy-to-use.