I’ve been doing technical writing of one sort or another since 1999, when I was doing QA for Altec Lansing’s R&D branch in Kfar Saba in Israel. Back then we would put out innovative, new audio related devices like (gasp) USB audio devices that worked on Windows ME and 2000. They were buggy and setting them up wasn’t the straightforward thing that it is today.
We needed docs.
We had some hoops that users had to jump through, and we needed a way to document what they were, what the edge cases were, and how to diagnose and fix all of that stuff. It needed to be nicely packaged, cleanly formatted, and accessible to users who installed our helper application. I found Robohelp, which created standard help applications, which could be added to our install.
During our QA process we would identify the issues, document what we thought was salient, and organize it into the help file that was bundled with the device. I was 19 at the time, and I had zero experience with this stuff, and it was an immensely naive process. But, it just felt like the right thing to do for our users, and my manager didn’t explicitly tell me not to.
It’s been 24 years, and since then I’ve done documentation for a bunch of projects. The scale has grown, and the way that I look at those types of projects has substantially changed.
I have some thoughts about what makes for good docs and I’d love to share them with you if you’re interested.
Core Concepts
Id like to start with a set of more concrete rules that I believe are critical to a documentation product’s success.
Docs should use small words to describe big ideas – so don’t use flourishy words or complex sentences to describe what can be said in simpler terms. You will lose users along the way and it isn’t worth your writer’s ego.
Docs should tell a story when you can – because a personal, relatable set of tasks that tell a tale will be more engaging and memorable for your user than an abstract set of instructions.
Docs should be searchable – because seriously: this is a no-brainer. If your docs are not easy to find stuff in, your users won’t find what they need.
Docs are almost always part of a larger strategy – and this is especially true when it comes to software products. This touches on the larger topic of developer advocacy, but in short: your docs should be supported by video tutorials, real use examples, and live technical support.
Docs should be tested – because you may be sure that everything is right, but without real users, like with any other product, you won’t know for certain. Test it and test it again.
Holistic docs are well-designed Products
When you learn a new programming language,
