One of my guiding principles behind writing & reviewing technical documentation is "Remove the burden of thought from the customer." After all, our customers are NOT getting paid to read documentation. They're not even getting paid to figure out how to program in LabVIEW. They are getting paid to solve problems.
So when I'm writing or reviewing technical documentation, I think to myself: how hard would a customer have to think in order to decipher this documentation? Hopefully the answer is "not very hard" because time spent deciphering the documentation is time not spent curing cancer, controlling photon beams, developing alternative-fuel technologies, monitoring structural health, and so on. But if that's not the answer I get when I look at the documentation, I have a number of ways to bring the effort level down.
- Speak your language. This one is difficult to do because the first people to define terms are the engineers who write a feature specification. As such, they define the language implicitly when talking about their feature, so because we use those specs as basis for documentation, we often repeat their language and incorporate it into headings. But we shouldn't. Compare "Using the Throughput Control" with "Achieving High Throughput". Which heading are you more likely to notice? I'd bet it's the one that speaks more to the task you want to do than the feature we are providing.
- Use pictures for visual products (like LabVIEW). Pictures improve a reader's ability to scan the text instead of requiring them to read a bunch of steps, provide anchors on the page that serve as reference points when switching back and forth between windows, and make the help look more colorful and less intimidating.
- Provide examples. Examples tell stories that can match your application, so you're more likely to notice and understand the explanation in that form. Examples also are the difference between high-level, theoretical statements like "Use the Blah API to optimize throughput when transferring data" and more low-level, specific statements, like "For example, if you are monitoring the temperature on a wireless node over a network, the BLAH API increases throughput significantly compared to the BLAH2 API. Here's why ...."
- Answer questions up front. If the LabVIEW API provides you two different ways of doing the same thing (and very often we provide more than two ways), you shouldn't have to wonder when to use a particular option. We should tell you. This issue is particularly helpful in the FPGA realm, where placing a checkmark in a single checkbox can have large timing consequences when it comes time to translate your design into hardware. At the very least, the documentation should make you aware of the trade-offs in checking that box vs. not checking that box.
- Be consistent - You'd be surprised at the amount of effort that goes into ensuring consistency among terms like "PC", "computer", "system", "machine", "console", "host", "target", "execution target", "remote execution target", and so on. This issue crops up even more in the FPGA/RT realm where you have one or more host computers connected via network to remote, embedded PXI or cRIO chassis. What the heck do you call all these things? And we still have a ways to go.
(Five points to anyone who noticed the inconsistency in how I punctuated this bullet item compared to the previous ones.) - Provide direction. At no point should you ever be wondering "What do I do next?" As Al talked about, technical writers have a number of ways in which to provide direction, both visual and textual.
These are just a few ways in which we can reduce your time spent thinking about the documentation and get you back to your task at hand. Unfortunately our ability to excel at these tasks are limited by two rather large factors:
- Lack of knowledge about what customers do, how they think, and what they want to see in documentation. This is a particular problem in the technical communications department where we have even less access to customers than general R&D. Click those feedback links, folks!! They are at the bottom of every help topic LabVIEW ships, and also for some other products:
We receive every piece of feedback and review it, even if we can't always act on it because ... - We're a for-profit company with deadlines. That's the nature of the biz, folks -- we have to ship a product on a given date and we can't always take the time to be 100% perfect in our documentation. But we can keep trying.
This post was inspired by not only thoughts I've had for the past few years, but also a post I saw about a restaurant removing the burden of thought from its customers by providing pre-calculated tips (15%, 18%, and 20%) at the bottom of each bill. The author (a tech writer) writes:
This document saves the user the grief of having to manually calculate the tip. It considers the needs of the user and immediately fulfills them, like any great document should.Exactly, man. Exactly. Instead of making tip-calculating a chore ("Let's see, divide by ten ... move the decimal over ... now multiply again by the bill amount ... wait .. where's my cell phone calculator?!") the pre-calculated tip removes the burden of thought from the customer, thus reducing the pain of this task (and reminding them to do it at the same time), thus lowering the barrier to doing the task, thus making it more likely that the customers will complete the task (in a satisfactory manner and with a minimum of pain).
Of course there are societal norms around tipping that make it likely to be done anyway, but again, the point here is that the documentation removes the burden of thought and, in doing so, actively aids the user in completing the task.
Genius. We should be so lucky to have documentation that is so comprehensive and user-focused.
