Movement in Information: Moving toward goal-oriented documentation

Writing a great tutorial is an art form. There are several requirements for a successful how-to exercise:

- The user needs enough information to successfully complete the task.

- The user needs to move through the exercise in a reasonable amount of time.

- The user needs to learn several basic concepts that will continue to be useful outside the context of the tutorial.

A common thread in these requirements is the sense of motion. The user is moving, gaining, accomplishing and completing. Even at the end of the tutorial, the user should feel like he is still moving toward success for the real reason he accessed the documentation – to make progress on his own project or task.

It's all too easy to get bogged down in an overly-thorough exploration of concepts. You can't help every user with every possible use-case unless you're both generalized and systematic in topic coverage. In the midst of all that detail, remember that at the end of every completed documentation topic, even if it's not a tutorial, you should be able to answer the following questions:

- What tasks can the user now complete that he couldn't before?

- What is the next logical task (or tasks) that the user would like to complete using this new information?

The end of a topic can feel like you've led the user up against a wall unless you provide some logical directionality based on the answers to these questions. The flow of information can happen graphically, textually, or with user-defined input.

Graphical directionality

Who doesn't love a great flowchart? Flowcharts can show users a clear map of where the documentation can take them. It can also offer them choices based on their goals. For instance, here's a simple flowchart example from Wikipedia:


If you were using this flow chart for some technical lamp-specific documentation, the flowchart might be an image map that allowed users to click on the step that defined their problem. If the user clicks on "Bulb burned out?" you might provide a topic on how to replace a light bulb. How many technical writers does it take to write a topic about replacing a light bulb, anyway?

At National Instruments, our NI VeriStand documentation is one of our finest examples of graphical directionality and navigation. In the web version, the flowchart provides a full map of the documentation landscape and puts the navigational control in the hands of the user.



Most users skip straight to the topic of their interest. In the installed version of the help, a miniature version of the flowchart perpetuates throughout every topic in the map, providing a consistent graphical navigation experience throughout the tutorial.

Textual movement

There are specific challenges associated with creating a sense of movement in textual documentation. Sometimes it's just not possible to spend the time and resources creating a complicated flowchart or sitemap to give the user a graphical overview of your content. However, there are several tricks you can use to help the user feel like he's still moving successfully through your content.
- Add contextual identifiers based on what the user would logically do next with the information he just acquired in the current topic. Use words that imply flow, such as "Next", "Upcoming" or "Review".

- Give users the ability to skip right to the "meat" of the documentation – the part where they actually start on their own project or task. If you have a less formal documentation set, provide links such as "Fire it up now" or "Get moving". For more traditional documentation, provide a link in each topic to "Start your first project" or "Open the software environment." This gives the user a feeling of "ready when you are."

- Consider a textual navigation option for the user who lands on a topic and finds the information too basic. "Already know this concept? Maybe you want to check out the specifications for creating your own model or build a new framework." This gives a more advanced user a jumping off point from a basic topic.

User-defined paths

This might be the most complicated yet most user-focused implementation of directionality in technical communication. And we're all about the user, right? Ask him where he wants to go and what he wants to do. How can the user define his own path?

- Search

- More search

- Even more search

Your help system's search engine is the most important tool the user has at his disposal for finding the content that's relevant to his particular problem, project or task. Search is the user's way of providing his own movement through the help system, and it's the one users will choose most often. Just make sure that when he lands on results, you have some of the above tactics in place to provide him with a sense of motion as soon as he becomes engaged in a topic.

Keep on moving on
If your documentation is successful, the user will quickly move on to proficiency with your product and efficiency with his tasks. Always remember to help the user feel like you're moving him toward that goal.

#2 With a Bullet

Hope ya’ll don’t mind a little horn-tooting!

In a Glassdoor.com survey, NI’s been named the second-best tech company to work for, coming in behind Juniper at #1 and Google at #3!

Can’t say I’m surprised :-)

If you look at the site’s overall company ratings, we come in at #13, just behind Kraft. If only we had the power of mac & cheese, we’d be better than they are, I know it …

The War on Error

Funny post from Andrew Brooke, a new blog I’ve added to my RSS feed.

The troop surge represents a 43% increase in the number of soldiers. Can you imagine the effect if a company increased the number of its tech writers the same amount? It would annihilate much of the company's misinformation and missing information, a victory in war on error.

Camel Case & Linux Documentation

A couple tidbits for ya today:

• LabVIEW, VeriStand, FieldPoint, CompactRIO, iPhone – what do they all have in common? Their product names use camel case. (h/t to DF)
• The sorry state of Linux documentation; from a user’s viewpoint.

Halloween Demo Day

 It’s a tradition: Every year on Halloween (or as close to it as the work week will allow), tons of LabVIEW developers set up shop at their desks and demonstrate features or products they’ve been working on to all comers. The email goes out to the entire company (in Austin, anyway) and for two hours, (most) work stops as people come by to check out what we’ve been working on.

Today’s that day! I just spent the past half hour blowing up balloons and attaching them w/ribbons to bowls of candy that will go at each demo station. I’ll post pictures or videos if I get them, later.

Preview of LabVIEW 1.0, 1986

In the comments on my last post, Yair pointed me towards this preview of the LabVIEW 1.0 beta, all the way back in 1986. Enjoy!

Interesting Articles

• Here’s a review of the original Macintosh, done in 1984. It’s amazing to read this now with 25 years of perspective and realize both how different it was and how similarly things still work today. But even back then some people seemed to “get it”.
  
  When LabVIEW was first released in 1986, it was for the Mac, because that was the dominant graphical platform of the day, and LabVIEW is and has always been a graphical language. Makes sense to me. (We actually have a couple LabVIEW R&D members who’ve been around since version 1.0 – if you came to NIWeek in 2006, you saw them present onstage.) It wasn’t until 1992 that the first Windows version appeared.
• Learn information better by getting it wrong first. This is an interesting idea, and it makes sense to me. Answers are always better when they come from within. Here in LV R&D we encourage tech writers to find answers to their problems (given the proper resources) before asking others for help. This often involves getting it wrong. But even outwardly, I employed this concept when I designed the Statechart Module Getting Started tutorial. How? I instructed users to build a broken statechart – and then try and run it. The idea is that the resulting error would serve as a sort of opposite-approach to good statechart design – e.g., here’s what not to do. It also gets users familiar with the error-reporting mechanism in the software and one of the key rules of statechart development.
  
  I guess the challenge is that if you fail too much it becomes frustrating and demotivating, so there’s a fine line to walk. We certainly don’t make a habit of publishing documentation that leads to failure :-)
  
  
  

Interesting Articles

I find myself reading a lot of tech news sites. I sometimes email these links out to developers or other technical writers if they are interesting or have applications to LabVIEW/NI, but I figured, why not share them with the world?

Here's are a few things I came across lately:

• Don't offer preferences to users if you don't have to. I think about this sometimes as we design software here ... oftentimes I'll hear developers arguing over how a feature should work and I'll think "just make it a user preference." But recently I'm starting to feel like users can get overwhelmed by ginormous, scrolling Options dialog boxes. (Not to name any names, haha.) Similar to BBEdit mentioned in the article, the version of Lotus Notes we use at NI has a type-ahead filter in its preferences dialog ... so you can search for preferences among its ginormous list.
  
  I'd bet that a Jeff Foxworthy might say ... if you have to improve usability by letting users search through your list of preferences, you're probably giving users too many preferences. And I imagine that once you give users preferences, you can't remove those preferences in future versions. Because that ruins their editing experience that they've customized. Much better to not give the option in the first place and make an intelligently-informed decision about the behavior.
  
• Users don't read -- or, they read the absolute minimum. This is a running joke in our department. And by "joke" I mean "concern". Does anyone actually read our documentation? I think many technical writers have this concern. And I think the answer is "not unless necessary." Personally, that doesn't stop me from putting my best efforts into shipping quality documentation. But it does mean we have to keep things in perspective. Although we support and provide polish for the software, we are not the software. That should be priority #1.
  
• The science of irrational behavior. I find this article fascinating -- might have to pick up the book. I can this playing out when we determine ship dates -- but really, just about anything (a co-worker mentioned this behavior coming into play when determining how much to sell a TV for). The first person to make a guess sets the tone for the rest of the discussion. The Slashdot commentary on this article led me to learn about Planning poker, which is a) hilarious and b) really, really interesting. (If we do this at NI, I certainly don't see it.)
• Ubuntu's first bug. This makes some of our issues look rather trivial ...
  

I'm a little surprised I don't read any technical writing blogs :-) Maybe I should start ...

Leica & LabVIEW

Leica makes some of the highest-quality, precision-engineered cameras in the world. WIRED magazine recently caught up with them and took a tour of their facility in Solms, Germany. In one of the shots, you can see a LabVIEW application (designed by Ramitek GmbH) being used to test the M9, Leica's newest camera. It's kind of awesome to see LabVIEW being used to help control tolerances as fine as 0.0001 mm. That is tiny!!

DPreview.com did a similar tour back in August, and some LAVA forum members noticed additional screenshots of our software in use.

Speaking the Customer's Language

Small bit of background: I recently got (more) into digital photography and have been having a fun time dreaming of buying fancy-schmancy camera lenses. So I was checking out Sigma's web site and saw they have an "advisor tool". I clicked it and was presented with this:

This tool is of absolutely no use to me. Why? Because I don't think in terms of "Lens technology" or even "Weight". I think in terms of "I want to take awesome pictures of bands at concerts without having to wander through the mosh pit." or "I want to take awesome pictures of friends at house parties where I'm typically like 3-4 feet from my subject". Those are the first things I think about. Not whether I want "APO" or "DG" (whatever the heck those mean) technology, or whether my lens needs 7 or 12 groups, or even weight. Weight's definitely a factor, but that only helps me filter down my choices. It's not where I want to start out.

Here's my thought: pro/advanced customers will not use this advisor because they already know what lens they want to buy; they can just Google it to find more info, a review, or a price. They think in terms of "Okay, I need a lens that hits 200mm at f5.6." They don't need a wizard for that; they've got Google or their local photography store. And if they did need a advisor for that (to find out what Sigma offers in those categories), this one certainly won't do the trick.

The advisor's geared more towards beginners and semi-beginners like me who don't even know what's out there to match their needs, and we certainly aren't experts at terminologies like focal length and aperture size. And if that's the case, then this wizard doesn't speak our language, which means using it will frustrate me, and I'm more likely to try my hand at discussion forums or asking a friend, any of which might lead me away from Sigma.

I had a similar camera-related issue a few weeks ago. Setup: I know there's some camera-flash mode out there where you can fire the flash at the endof an exposure, rather than at the beginning. I have heard this is called "rear-curtain sync". I looked through my Canon Rebel XSi's manual for this term but did not find it, so I assumed that the built-in flash does not have this capability.

Wrong. It does. It turns out that Canon calls this capability "second-curtain sync". Why? No idea; perhaps they want to be distinct from Nikon and/or other camera manufacturers. But since I didn't know how Canon thought of it, I didn't know what terms to search for. So I didn't find the information I was looking for. Maybe this is beneficial to Canon because they can sell upgrades (Speedlite add-ons) easier if customers think their built-in flash doesn't perform as well. I really hope that's not the case, but you never know :-)

This issue comes into play in documentation. You have to think like a user and talk like them also. If you do that, search hits will come up and index entries will be informative, and users will find the information that they're looking for. And that's what we all want :-) This is especially true of topic headings, which are displayed more prominently in topics. That's why I named this topic the way I did. I called it "Specifying the State in a Region that Executes First" because I imagined that would be the question the user has in their mind: "I have a state in a region; now how do I make sure that this state executes first?"

I could have called it "Using the Initial Pseudostate" and been done with it. But who the heck knows, out of the box, what an Initial pseudostate is? (Outside of the development team, I mean.) I feel that because I used a task-based heading, users are more able to find the information they're looking for. It's not always easy and it doesn't always work, but I feel that results in higher-quality documentation and a more positive experience for customers.

What products or help files have you run across that speak your language?

NI Week: Where NI Technology Gets Real

As NI's newest tech writer, I feel like it's part of my job to experience as much of our technology as possible. In my day to day work, I can do this by talking with developers about the product and learning from them about how the customer might use the new features they're working on. Sometimes I get the chance to see a demo, but it's rare that I get to see the end result from a customer's application.

As I entered the Austin Convention Center on Tuesday morning, there was a lot of energy in the (chilly, air-conditioned) hall. People were flooding up the escalators to get a good seat for the morning's keynote with Dr. T. It was truly amazing to see the community of engineers who are so passionate about their work and about the technology. Dr. T's talk was fantastic, as were the keynotes from the other speakers. What really fascinated me, though, was the multitude of demos set up on the stage each morning.

We got to see robots climb stairs and see a robotic arm offer up a first aid kit with excellent comic timing. We even got to hear the Star Wars theme played on a laser harp:



Each demo showed the amazing range of applications where NI technology can be utilized. On the third morning, the demos highlighted socially responsible uses for engineering innovation, and groups presented their vision of a better future. Mashavu demonstrated their networked health solutions designed to make it easier for people in 3rd world countries to get in contact with a medical professional. Envirofit, born out of CSU's Engines and Energy Conversion Laboratory, showed off their low-cost cook stove that eliminates much of the dangerous pollution associated with traditional cooking methods in developing countries.

For me, NI Week not only showed how the products I write for become tangible systems, but also showed how my work and the work of our developers and engineers can be connected to the rest of the world. At NI Week, I got to really see our technology come alive. Sometimes it can be easy to lose sight of that big picture, so I was grateful for the opportunity to reconnect.

Web LabVIEW UI Builder - Doing Something New with the Help

Wednesday at NIWeek, we took the wraps off of the newest project I've been working on - a way to host LabVIEW in a Web browser, letting you build VIs without installing ANYTHING on your computer (ok, that's not the whole truth, you DO need to spend 30 seconds downloading the Silverlight runtime engine!) Just like Gmail, Google Docs, et al let you access email and spreadsheets without installing ANYTHING on your computer except a Web browser and a few standard plug-ins.

Our model allows you to build thin client VIs -- VIs whose front panels serve up UIs in a Web browser (w/Silverlight installed) and whose block diagrams connect to Web services, running on a remote cRIO/PXI/whatever target, that exchange data with a device you want to control and/or monitor. Up until now you've had to build these UIs in Flash, Flex, AJAX, or whatever. Pretty soon you'll be able to do it using just G! Yes, one language to rule them all ...

After you deploy this VI, you'll get a special URL for it. You then can connect to it anytime you want to view data from/send data to the device (in our keynote example, we used a wind turbine). The key is that you DON'T NEED LabVIEW INSTALLED to connect to this VI and control/monitor the device! You just need a Web browser/OS combo that Silverlight supports.

(Wow, I'm actually getting into a draft of a help topic here!)

I'm the technical writer for this project and it's something that's been very exciting to work on for the past few months. The main reason is that in planning the help system, we are going to be doing some very cool things. Granted they won't be mind-shattering, but given NI's traditional reliance on installing/printing CHMs and PDFs for help topics, the Web LabVIEW UI Builder (WLVUIB ... uh ... no) help will be pretty slick. For example I hope to reduce the time it takes to update the help, and I also hope to shrink the distance between developers/tech writers and users by taking advantage of some community-focused features. After all, you know best how to use these products. You should be able to share that knowledge easily with other users and with NI if you so choose. It's a win-win.

I also hope to bring videos, tags, and RSS into the mix. The overall experience should be more interactive than an installed CHM/PDF file, while still enabling you to find the information you need in order to get your job done.

Not that you'd sign up to use this product solely for the help, but if you participate in the pioneer, you'll get a sneak peek at it, of course! If you're interested in being a part of the pioneer program for Web LV UI Builder or any of the other few pioneer programs we have going on, head over to ni.com/day2 and let us know.

The LabVIEW 2009 Help

In case you're wondering just what we do all day ... or all year ... the LabVIEW 2009 Help system is now available online. It contains the help for the LabVIEW Base/Full/Pro development systems as well as each individual module and toolkit.

Bet you didn't know we have so many LabVIEW add-ons! Did you know we make a toolkit to help you develop adaptive filter algorithms? (You know, like if you wanted to create some noise-cancellation headphones.) Or that we have software to help you validate your code with unit testing? And that's not even counting the add-ons that let you run LabVIEW in real time or on the Windows Mobile OS.

No, I swear I haven't joined the marketing team. I just think back to all the work we put into these help systems and feel really good seeing them online like this for public consumption :-)

Our online presentation is not the most sophisticated way to do things. You can see that we throw our stuff up there as static HTML pages. In this day and age of content management systems, having a collection of documents linked together just with hyperlinks seems pretty outdated. It's a travesty, I tells ya! Fortunately there are people at NI who realize this. I hope one day we can implement something a little more modern -- and that it won't be outdated if/when we roll that system out :-)

Announcing LabVIEW 2009

Yeah, the cat's out of the bag! We're publicly announcing LabVIEW 2009 today. If you're attending NIWeek next week, you'll of course get a more in-depth look at it, as well as a chance to pester developers about it :-)

I'm pretty excited about the Enhanced Block Diagram Cleanup feature. I used the first version of this feature a LOT in LabVIEW 8.6 when developing some VIs here for internal use. It is amazing but of course it had its limitations; those have largely been addressed in this release.

It's always a little strange seeing these feature names up on the web; they began as internal feature specifications and we've been talking about/referring to them for a long time now, haha.

These Sentences Confuse Me

From ESPN:

Jamie Moyer allowed seven baserunners before recording an out in the third inning. Somehow, none of them scored.

I read this bit and did a double-take. This makes it sound like Moyer did the following:

• Allowed seven baserunners in the third inning
• Did not record an out until the eighth batter of the inning
  
• Did not give up a run during this time
  

If you follow baseball, you might remember there are four bases. You can allow a maximum of three baserunners before the next one drives in a run. So to allow seven runners in one inning before recording an out and not allowing a run seems pretty impossible to do.

Moyer's good, but he's not that good.

(Baseball Terminology 101: We say "allowed baserunners" instead of "allowed hits" here because not all of the runners reached base on hits. The article mentions that Moyer allowed six hits in the night, so if he allowed seven baserunniners, one runner reached base on an error or a walk, neither of which count as a "hit". But you still get on base. Baseball sure does split hairs a lot.)

Continuing to read the article you'll find out that Moyer allowed two baserunners in the first inning, three in the second, and two in the third -- total of seven allowed, now -- and none of them scored. Oh, that's what the article meant -- not seven baserunners in the third inning, as implied, but seven baserunners through two and a third innings. And none of them scored.

(Baseball Terminology 101, #2: Recording one out counts as "a third" of an inning, since there are three outs per inning. So "two and a third innings" means Moyer pitched two innings and recorded one out in the third inning. And when we say "inning" here, we really mean "half an inning", since technically an inning consists of a top and bottom half, and the pitcher only pitches one of those halves. Still with me?)

So Moyer really did the following:

• Allowed seven baserunners through two and a third innings
  
• Got the requisite six outs over the first two innings (this is implied by the first bullet above, but I thought it better to state explicitly here)
  
• Did not give up a run during this time
  

Were I editing this article, I would suggest that the statements above read something like:

Jamie Moyer allowed seven baserunners through his first two and a third innings. Somehow, none of them scored.

Much clearer, I think.

Sarah Palin's Resignation Speech, Edited

I'm not trying to start anything political, but I think this is pretty interesting. This is often the end result of documents I write, although we use Adobe PDF Reader to mark comments and distribute them electronically.

I like how Vanity Fair has separate literary, research, and copy editors. Often at NI we have to combine these roles into one person.

Photo used from http://www.flickr.com/photos/nicmcphee/ / CC BY-SA 2.0

"At" vs. "On" and What it Means for the iTunes Application Store

Lonely Sandwich talking about how prepositions affect the perception of the App Store:

I could say I bought a song on iTunes, but when I speak of it like that, I think of iTunes as more of a network for content rather than an outlet, much in the same way I’d say I saw 30 Rock on NBC or heard my favorite song on my favorite radio station. So does this mean that Apple likes to think of its iTunes Stores as networks? And if the iTunes App Store is a network rather than a retail outlet, what does that make the apps it sells? And herein lies the real question: is an app a product or is it content?

Only extreme nerds think about stuff like this. Hence why I find it interesting :-)

The Rubber Duckie Test

Okay, this sounds kind of odd, but hear me out. A developer friend recently told me about the "rubber duckie" method of coding. In a nutshell, you as a software engineer place a generic rubber duckie on your desk. Every time you make a big coding decision or implementation, you explain how it all works to the rubber duckie. If you find yourself straining for an explanation, or if you find yourself unable to even come up with something logical, stop. The duckie has served its purpose -- it's helped you expose a bug or design flaw or implementation flaw that otherwise might have gone unnoticed (until later when the build breaks and it's your fault, or a customer's app crashes and you lose a $2k sale).

This is why technical writers are valuable. We are living, breathing rubber duckies, forcing you to explain your code and decisions (so that we can explain them to users) and thereby helping you uncover errors, inconsistencies, or inefficiencies in your design. And also, because we're human beings, it doesn't look like you're trying to hold a conversation with a squeaky toy.

Things You Wish We Said in Our Docs

An example of some great, actionable user feedback:

3. From the docs: "When you are ready to upload the code, select the correct serial port and NG board type on the Tools menu". This made me want to tear out my own eyes. What are the correct settings!!?

We (LabVIEW technical writers, product support engineers, applications engineers, and yes even developers) try to monitor our forums, we really do. Especially for LabVIEW Base/Full/Pro and especially during beta periods. But it's not always possible, and some things get lost in the shuffle. So we (the technical writers, now) do try to solicit your feedback directly from the help via the feedback link ("Submit feedback on this topic") at the bottom of nearly every help page. Since we introduced this link several years ago, we've received a ton of great feedback, most of which we can do something about :-)

The forums and the increase in user participation always bring up the issue of wikis and user-generated (or at least editable) docs. I'm a little swamped right now so I don't have time to discuss these issues, but rest assured I'll give them the full treatment at a later date, because that sort of stuff is really interesting to me.

But for now: what sorts of tips/tricks/tidbits/information do you wish were in the LabVIEW docs?

Hat tip to Janet Swisher for the link in the first sentence.

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?

What's Your Bug to Writer Ratio?

Some stats on Microsoft's technical documentation for communication protocols:

1,660 identified bugs ... Nearly 800 Microsoft employees are working on the technical documentation ... More than 20,000 pages of technical documentation ...

That works out to:

• 2.075 bugs per writer
  
• 0.083 bugs per page
  

I don't know about you, but I think those are excellent ratios, even given the fuzzy numbers and imprecise information — e.g., "working on technical documentation" probably doesn't equate to "full-time technical writer". If MS dedicated an entire week to fixing these issues full-time, I bet they could resolve them all, or at least the vast majority of them. However, you just know that some of the bugs are really vague, like "Provide more information about x". Those take a long time to fix.

But the main point of the article is that MS isn't fixing documentation bugs quickly enough to satisfy the DoJ:

Lawyers for the [19 states suing Microsoft] have complained repeatedly that technical documentation issues, or TDIs, are opening faster than Microsoft can close them.

TDI?? ... That's all we need, another TLA.

Well, I'm just happy the DoJ isn't scrutinizing our docs like this :-)