I Don't Want You to Think

No, really, I don't! At least, not when reading my documentation.

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.

Error Codes

I bought a new lens for my digital SLR a couple weeks ago. As I was checking out at the store, I noticed that the staff was setting up for an instructional session of some sort. I asked them which session it was, and the clerk said it was their digital photography basics class. He said the class came about because the staff was having to answer all sorts of these basic questions and do all these quick fixes (white balance settings, etc.) for everybody. So they started giving classes so consolidate their answers into one place, so their staff wouldn't have to spend so much time answering these little one-off questions.

"Sounds similar to my job," I replied, and I explained what I do. He then said something along the lines of "Look, if you guys do one thing for your users, do this: give them human-readable error messages. I hate when I'm fiddling with something and I get error -463259 or whatever. Just tell me that the lens cap is on or the filter size is too small or something!"

I laughed because I know all to well what frustration he's talking about. After all, I use software (and other error-generating products) too :-) Luckily we pay a good bit of attention to error codes in LabVIEW. Most of the descriptions are edited by a technical writer in the same way we would edit any other piece of documentation. And for our non-native English speaking users of LabVIEW toolkits and modules, we translate the error codes into several languages, even if we don't translate the product itself. If you're frustrated with our software, there's nothing worse than trying to read error codes that are written in a language other than your native one. (Well, that's not totally true; I could think of a couple things worse than that!)

Yes, we have wonky numeric error codes, and sure there are spots where we are probably uninformative. But overall I think we do a good job of communicating why the error occurred and how you could go about solving it. Of course sometimes we can't give this information because we simply don't know it. There could be numerous causes for a particular error, and only one of them would be relevant to what you're trying to do.

What do you think about LabVIEW's error code documentation? Is it helpful to you? How could we improve it?

Tech Writing = OCD?

Over at Ars today, Erica Sadun gives thanks for the iPhone SDK's documentation:

Thank you for the kick-ass SDK documentation. I know you have employed many OCD victims who would otherwise be wandering the street picking up litter and tidying our world and instead aimed them at creating precise and glorious help pages. Sure, it takes about five years to download each API update but oh, the beauty of it when it finally is installed!

I've often had a similar thought about my team. The LabVIEW Documentation team consists of some of the most detail-oriented people you will ever meet. We debate using "attend" vs. "participate in". We agonize over "both" vs. "either". We spend half an hour brainstorming the placement of a level 2 heading and worry over its effects on the help file table of contents. We nitpick over parallelism in bulleted lists, consistent descriptions of everything, and so many other things. We pester developers with questions, trying to nail down that one perfect way of describing a feature.

And the worst part about it is -- we like it :-) (Well, at least I do.)

I don't know if it qualifies as OCD, but I'm sure there's some sort of term for how we are. "Grammar Nazi" comes to mind, but that's really pejorative and, to me, relates to Web forums where you're correcting the grammar of strangers in a situation where that activity is not expected or encouraged. "Anal-retentive" could be another description, but again, that feels pejorative :-) "Detail-oriented" is good, I suppose. I would say that we just care a lot about presenting information in the most helpful, unambiguous way possible.

Ahh, see, I'm doing it again!

From a Distance

(Side note: Every time I see the acronym for Subject Matter Expert, I think of Smee from Captain Hook. Every time.)

Through a co-worker's blog, I came across a post about sitting near your SME at the office. I cannot agree more emphatically. At NI, most of technical writers sit in the same general location as the engineers for whom they write documentation. For most of my three years here, I could swivel my chair 360 degrees and have a direct line of sight to all of my engineers.

I strongly believe that this proximity is key to establishing quality documentation. When the barrier to interaction is low, you are more likely to ask SMEs questions. If you have follow-up questions, you don't have to wait for these follow-ups to percolate through the developer's email inbox -- you can walk over to their cube and have a discussion. The developers are more likely to take your presence and schedule into account - meaning, if the release date slips or if they decide to add six new features, it's easier for them to inform you in person (where, again, you can ask follow-up questions on the spot). Because they don't have to work as hard to tell you about these changes, they're more likely to tell you. You're also more likely to socialize casually in the office, an action that improves interpersonal communication in general.

Phones and email and instant messaging are wonderful and great ways to assist technical writers. But oftentimes there's no substitute for face-to-face communication. Especially not when you're trying to ascertain the finer points of model predictive control :-)

So for all of my time at NI, I've enjoyed these benefits. This situation changed last year when I wrote the documentation for MATRIXx 8.0. During that project, I had to be aware of a small time-zone difference when calling and emailing my engineers. This was only a problem early in the morning and at lunch :-) To ease the pain, we had numerous conference calls, and in 2006 I even spent two weeks at their office so I could better understand the product during its development.

But at least my developers were in the office at the same time I was. This situation changed even more drastically when I begun working with developers in other countries. At this point you're introduced to the fascinating world of late-night (or early-morning) conference calls, reviewing & commenting on documents electronically, and never actually meeting the people you're working with. Add in language considerations, and you have a whole other ball game.

I wouldn't say that this distance decreases the quality of the documentation. However I would say that you don't get as many chances, or you have to work extra-hard, to keep the quality of the documentation consistent with what you've been doing locally. For example, consider this situation:

I email a developer in our Shanghai office at 3 PM CST. They don't get the email until 8 PM CST (9 AM their time). At this point I'm obviously not at work. I don't get their reply until 9 AM the following morning. This email has made its round trip in 18 hours. Compare that to 2 hours or less for a typical email to someone in Austin, or even California.

This fact underscores the importance of being precise when you're corresponding remotely. What if I have follow-up questions, or need clarification, to my Chinese co-worker's reply? I send this hypothetical follow-up email at 10 AM. Then it's another 23 hours until I get all of my information.

Total time for information flow: 41 hours. That's almost two days during which I am stuck on a problem or unable to do my job. And I'm assuming here that the developer actually has time to answer my question during their workday. If not, add another 24 hours onto the cycle.

I see a couple ways to mitigate this issue. One, be as detailed and precise as possible when emailing remotely. Treat your co-worker as an audience of one. Anticipate questions they might have and answer them in advance. Two, you can stay up late or get up early so that you're both in the office at the same time. Three, and this is the most effective measure, try not to rely on remote locations for decisions or information. (I know, I know -- easier said than done!) The finer points of this solution include making every use of local resources. You could spread knowledge around so that no one person solely is dependent on any other person (we also like to call this the "hit by a bus" defense). Four, and this is the most fun measure (at least for me), travel to the remote office and spend some time there :-)

(I just realized that the above paragraph probably should be a bulleted list.)

This situation obviously isn't unique to technical writing. These intercontinental concerns happen also with software development, upper-level management decisions, and technical support. Thankfully, at least in my case, you could get some fantastic travel opportunities out of this way of working. Which is my own very subtle way of segueing into the fact that I will be living and working in Shanghai for at least the first half of 2008. I leave in one week. I look forward to posting about my international technical writing experiences :-)

Source Code Control for Documentation

Jim Kring and Joel Sumner have posted recently about the benefits of source code control (SCC) for software development. At NI, the technical writers also use SCC for our documentation development. For those who are unfamiliar with SCC, it works like this:

• Your source files are stored in a repository on a central server.
• To edit a source file, you must "check out" the file. Checking out a file downloads a copy to your computer, where you then make your edits. Typically, checked-out files are marked as such so others cannot check them out at the same time.
  

(You can configure some SCC programs to allow multiple checked-out copies simultaneously. The SCC program then can merge multiple changes back into a single file. I tend to distrust this method; I much prefer the security of knowing I'm the only one with the file checked out for editing.)

• When you are done making edits, you check the file back in, which involves uploading it back into the central repository. Others can then synchronize to the latest version of the file that contains your edits, check out the file themselves, and repeat the process.
  

SCC for documentation, at least the way we do it at NI, has many benefits that parallel what Jim and Joel describe for software.

• Because only one person can check out a file at a time, SCC ensures you don't overwrite ("blap") edits that someone else made. This benefit mainly is for larger groups of writers that all work on the same source material, like in LabVIEW.
• Because the most recent copy of the file is stored in a central location, everyone knows where to go to get the freshest copy of all necessary files. Again, this benefit mainly applies to groups of technical writers.
  
• Ensuring you have the latest version of a file is as simple as right-clicking a file and selecting Sync to latest revision.
• SCC allows you rewind time back to when a file was good. If you check a file in and suddenly the XML won't transform or the HTML looks wonky, you can synchronize to a previous revision of the document when you know everything was good. The SCC program can handle this revision history automatically, so you don't need to spend time renaming files, copying files to different directories, or marking files as read-only.
  
• Some SCC programs feature an integrated tool for differentiating ("diffing") between versions of files. With the click of a button you can highlight differences between the document you're editing and what's stored on the server. This tool is really powerful for documentation because you can see exactly what changes someone else might have made to your document. (Or, if you're a lone writer, what changes you made to your document!) Because the changes are highlighted onscreen, you're not distracted by unchanged text.
  

For this to work, the file must be stored as text (XML, HTML, etc.) and not binary (FrameMaker, MS Word, etc).

• SCC allows you to annotate the changes you made every time you check in a file. These annotations can be as simple as "Fixed some typos," but more descriptive annotations are even more helpful. By clicking "Revision history" in Perforce, the SCC program NI uses, I can see who's done what to the file. Some file histories extend back to 2001 and provide a rich timeline of the file's evolution over time. This benefit helps not only large groups of writers, but even lone writers who want a quick record of what they've changed and when.

I find that the only drawback with SCC is the overhead of editing a single file, which involves the following steps:

1. Launching Perforce. (Actually, I usually keep it running.)
2. Navigating to the file's place in the repository. (This can be slightly time-consuming if the server is being slow, the file is located on a different server, or if the file is buried in a deep directory structure.)
3. Checking out the file.
4. Launching the program to edit the file.
5. Editing the file.
6. Saving the file.
7. Using Perforce to annotate the changes you've made.
8. Submitting the file.

Without Perforce, only the opening/editing/saving steps apply. But you then would lose the benefits of knowing that these changes are permanent, trackable, and eraseable. These benefits are essential in a mid-to-large size organization like NI.

Also, it can get confusing if you sync to a file and then delete it by using Windows Explorer. In this situation, the SCC program still thinks you have the latest copy of the file, so you have to remember to force the program to actually download the file again. But this is really more of a "user error" issue, although it crops up for me frequently as I install and uninstall various development versions of LabVIEW on my computer.

For those of you who want to give SCC a try without spending a dime, check out subversion or the Perforce evaluation.