At the 2016 Southern California Linux Expo (SCaLE 14x), long-time tech writer and editor Bob Reselman will give a talk called The 7 Rules for Creating World Class Technical Documentation, v.2016, which is based on an article he wrote more than six years ago. In this interview, he offers an update to the rules, and talks about how attitudes toward project documentation are changing.
If you were writing your article for the first time today, would you have the same 7 rules for creating world class technical documentation? Or have the rules evolved since then?
Well, here are the 7 Rules:
- Dry sucks.
- Before you start, be clear about what you want your reader to do after you end.
- Write to a well formed outline, always.
- Avoid ambiguous pronouns.
- clarity = illustrations + words
- When dealing with concepts... logical illustration and example.
- Embrace revision.
The rule that has evolved most for me is #1: dry sucks. When I wrote the rules initially, I was a big proponent of humor as a way to avoid dryness. I've evolved to think that engaging content makes the work not dry. Yes, some of us still like humor. But the more I do this, the more I find that clear, reiterative writing that uses attractive, accurate, understandable illustration takes away from a lot of the dryness in the technical documentation landscape.
What are the most common mistakes you see in open source project documentation?
That's a hard one for me to answer. There is a whole lot more good stuff going on than bad. I think that the importance and prominence of the Read.ME file, along with markdown has made consistent, useful technical documentation a way of life for the development community. Yeah, things go stale, which is usual for any documentation over time, but all and all things are on an upward trend in text-based documentation, anyway.
Which projects stand out as having exceptional documentation? And which ones would benefit from a documentation overhaul?
I can't really point out to any one project because there are so many. But in terms of commercial work, I think the folks at New Relic are getting it right. They have a well-constructed taxonomy and the content to back it up. The company produces short, useful videos that get right to the point.
Also Akka.Net is doing an impressive job. The text documentation is visually clear and organized well. Each page of documentation shows the outline organization on the left margin, so you can read through or pick and choose. They've obviously planned things out. They are very big on making it as easy as possible for people to use their technology.
Of course, in terms of being able to present massive amounts of documentation, you gotta admire the work that AWS does. They are still a little lacking in terms of visual display of the UI when it comes to their HowTos, but overall, they do manage to capture and present a huge taxonomy that is more useful than not.
Have you seen attitudes toward project documentation—and the people who write it—change over the years?
For big companies and tool providers, the documentation is always getting better. The economics of the situation demand that they do everything to keep their user base happy. However, for smaller to mid-size companies, particularly those that have an IT department rather than a software development unit, I am not seeing the sort of progress I hoped for. The notion that any company that produces software or systems should have a technical editor on staff is still hard to sell. Either the hope is that one day they will hire a sole technical writer to make it all better, or they think that the current documentation efforts of the software developers are good enough. While it is true that all content creation needs to be generated by the subject matter expert, a good technical editor can teach content creators how to be more effective. Also, the tech editor understands the big picture, the overall taxonomy of the knowledge base that needs to be satisfied, as well as the style guidelines required to make the work consistent in the short and long term.
And then there is the continuing emergence of video as a documentation resource. I am going to talk a lot about video in the 7 Rules 2016 talk. There is a lot of work to be done.
I have a vision: 2016 will be the Year of the Open Source Haiku. What's your documentation advice, given via haiku?
That which we value,
should be well documented,
delightfully so.
4 Comments