Recently, I’ve been working on a project, mostly for the purpose of learning how to set up a modern Python project using the best tools currently available. Most of it is based on the Hypermodern Python series of articles, supplemented by my own preferences and research.
At this point in the project, I’m working on writing the docs, so I want to clarify my thoughts on what should go into them to make them as useful as possible.
It boils down to answering questions that people are likely to have. Good docs make it easy to find the answers you’re looking for. Generally, that means being concise, understandable, and organized.
Concise
The definition of concise is “brief, yet including all important information.” Saying what needs to be said in few words is a skill that can be learned over time, but it requires effort. Keeping it short makes scanning documentation to find what you need easier.
The “including all important information” is there for a reason, though. Thorough documentation shouldn’t be sacrificed for anything!
Resources for learning to write concisely are everywhere, so it may be worth investing some time in learning about this in a more structured way. Other than that, I think a process of editing previous writing is a good way to hone this skill.
Understandable
In some ways, this is the opposite of concise. You can usually pack more information into fewer words by using difficult-to-understand words or obscure grammar. There’s a balance to find here.
There are some tools that can help determine how difficult your writing is. It’s probably not a good idea to rely on them too much, but they can give a general idea. For example, this blog post has “an average grade level of about 8,” so it should be pretty easy to understand.
Along with finding the right words, having examples can make things a lot clearer, when applicable. They show concretely how to do what your words are describing.
Organized
If the answer to your question is buried somewhere that isn’t obvious, or it’s split between multiple sections, it’s going to be harder to find. My plan is to think about what questions are likely to be asked, then try to group sections based on that.
Initially, this should be easy enough. Most questions are likely to be along the lines of “How do I use X to do Y?” That will likely be in the docstring for X, for common or simple Y. Or maybe a page in the docs dedicated to Y, if it’s more complex.
Later, though, there may be questions like “How do I contribute?” or “Why was X decision made instead of Y?” Or any number of questions that don’t belong in a docstring.
Conclusion
There’s a lot that goes into writing good documentation. These are just some general principles, which really apply to all technical writing. I think getting them written down has helped me consider how they apply to my project. Anyway, if you manage to have concise, understandable, and organized docs, you’re already doing well.
What else do you think goes into writing good documentation?