December 16, 2009
- 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.
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.
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.
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?
- 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.
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 …
December 8, 2009
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.
December 3, 2009
A couple tidbits for ya today:
October 30, 2009
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.
October 26, 2009
- 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 :-)
October 23, 2009
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 ...
October 13, 2009
DPreview.com did a similar tour back in August, and some LAVA forum members noticed additional screenshots of our software in use.
September 17, 2009
August 7, 2009
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.
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.
August 3, 2009
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 :-)
July 31, 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.
July 28, 2009
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
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
Jamie Moyer allowed seven baserunners through his first two and a third innings. Somehow, none of them scored.Much clearer, I think.
July 21, 2009
I like how Vanity Fair has separate literary, research, and copy editors. Often at NI we have to combine these roles into one person.
April 17, 2009
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 :-)
March 23, 2009
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.
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.
February 12, 2009
"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?
January 23, 2009
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
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 :-)