Documentation is one of those areas that never feels quite finished. There are almost always areas that could be updated or improved in some way. In his talk at LinuxCon Europe, Chris Ward provided a crash course on ways to make documentation for your projects better, starting with thinking about how to answer the three W’s:
- Who are you writing for?
- What are they trying to achieve?
- Why are you writing this?
Ward points out that with documentation, you should “assume nothing.” Keep in mind that not everybody has the same programming implementation experience and history as you, so don’t assume that everyone understands the same techniques and methods that you know. What about a particular technique or dependency that you think everyone must have installed? There’s no harm in mentioning it anyway, just in case. It takes an extra few seconds, and everyone has a much nicer experience.
You should also have a solid elevator pitch, a quick, simple explanation of what your project does. Ward feels that “most ideas, no matter how complicated, can be reduced to a simple pitch that everyone can understand.” It’s fine if you lose some of the subtleties and detail, since you’re just explaining enough to allow a person to make up their mind if they’re interested in or not. They can dig into the rest of the documentation for details if they’re interested in learning more.
While API docs are great for describing how to interact with various components of the project, Ward says that API docs are not always enough. They don’t necessarily describe how someone can assemble them into something that makes sense as a component of another project. This is where a getting started tutorial on top of your API descriptions can help explain how to assemble these pieces together.
Consider Your Audience
Ward also thinks that it’s important to consider how people are getting to your documentation. Quite often people are not getting there from within the documentation itself, but from search engines that might drop them into the middle where you can’t guarantee that they’ve seen some previous steps that should have been completed in a certain order. There are techniques, like using navigation and links back to important concepts, to help with this.
You can also do a few things that make your documentation a bit more interesting. Interactivity can help readers understand a concept, and with most documentation being read online this is actually fairly easy to accomplish, because we have access to a wealth of rich media. A bit of storytelling can also be interesting. When we’re writing technical documentation, we’re not writing fiction, but there is no harm in trying to tell a story through examples or other narrative techniques.
Keep in mind that many people will use your documentation: marketing, search engines, managers, and more. So, Ward closes with this remark, “documentation isn’t just for developers. It’s actually read by a lot of other people, too.”
If you want to learn more about documentation, including more tips for managing, testing, and displaying your documentation, watch the full video of Ward’s talk from LinuxCon Europe.
