NI-TC 2006

Every year at NI, we have an internal conference for all the employees in the Technical Communications department. This conference, conveniently enough called NI-TC (for NI-Tech Comm) is in late October and lasts for two days. It's a time for us to bring everyone up to speed on what's going on the department. We have multiple presentations/seminars, a demo fair that showcases the neat products we work on, and (of course) a deck party with food, drink, and music. This year we had some cameras floating around, so I wanted to share the event with you...

Breakfast on Day 1 consisted of bagels, cream cheese, and a big fruit tray. Oh, and coffee of course! Breakfast on Day 2 was a plethora of breakfast tacos. Mmmm.



A group of us getting ready for the first presentation in the morning.

This year, we all voted on superlative awards, like "Most Likely to Build a VI for Home Use" and "Most Likely to Out-Nerd an Engineer." Yeah, it's dorky, but it's fun :-) Here we see Nick distributing a prize pinwheel to Kyle while Kip looks on.



Another group of us between presentations.



Colin (r) and me about to give our presentation. Colin's in marketing, so he's no stranger to a suit. But me being in R&D, well, let's just say I wear suits for only family occasions :-) But when you're presenting to a team of co-workers, it never hurts to look snappy, right? I thought it would be funny, given that I dress so casually all the time. Some people got the joke, but some didn't. In R&D, you wear a suit only when you interview!



Some of us watching a presentation on how Windows Vista's online help is different from XP's.



This is the demo fair, and we have Mark demonstrating the NI Vision Builder for Automated Inspection.



Again at the demo fair. Bradley gives us a hands-on sneak peek at Windows Vista.



Okay, the learning is over and it's time for the deck party!



One of our tech writers (Robert, on the left with the bass) plays in a local band called The Hackles. They graced our deck party and played some good ol' country music for us.

What We Do All Day

6-7 years ago, NI created a website, in partnership with Texas Tech University, that walks you through A Week in the Life of a Technical Communicator. Because the design is so 90s, and because the "star" of the web site is no longer with NI, in January 2006 a group of writers decided to update the site with a more "modern" look. (Wow, that's a lot of quotes here.)

The result is a new-and-improved A Week in the Life of a Technical Writer (notice the title change) web site. The goal of this site is to explain what we do all day. We have two audiences in mind: 1) prospective employees and 2) students who are unaware of what technical writing is - or at least what we say it is, because the job title can mean many things depending on where you work.

Creating the site was an interesting exercise in collaboration and group work. It took us longer than we'd anticipated to decide who to "feature" on the site, come up with a design, write the content, decide on the page navigation, and so on. We unveiled the site on Sept 8th, 2006, after nine months of planning and implementation. Some of the group members are currently writing an article for the STC's Intercom magazine based on the effort.

Anyway, check it out!

Guest Appearance on the VI Road Show

Every Halloween, the LabVIEW team sets up various demos of our products for other members of the company. This year, the VI Road Show invaded and caught some of what went on. The following video shows Varun, myself, and Alex discussing and demonstrating the LabVIEW Simulation Module. Beware the horrible scrolling CRT monitors!

P.S: I feel I should explain my bloody face :-) My costume this year was Ash from Army of Darkness.

Not an Engineer

I was re-reading the post about April's interview in the Statesman, and the last sentence stuck out at me:

...the fact that she is not a programmer or engineer serves her well as a tech writer.

This phrase is very true. I said the very same thing to a class of students at UTSA last fall, and I find myself thinking it at the career fairs I've been to recently. Many job applicants hear "technical writer," or sees what NI does, and think "I'm not a programmer" or "I'm not an engineer." To these students, I say, good.

We need more non-engineers and non-programmers looking at our products: testing them, writing about them, and polishing them via documentation or other means. We need creative people with non-technical backgrounds to push back on the developers and say "This isn't designed well" or "If I can't understand it, how will a customer?" After all, just because we're a tech company, that doesn't mean all our customers are technology oriented. Engineers and programmers are trained a certain way, which doesn't always include ease of use or user-friendliness. That's (part of) our job. So in these cases, being a non-techie is very beneficial.

So we don't need, or sometimes even want, you to be tech-savvy when applying for the open technical writer positions we have (hint, hint). When we're interviewing or looking at resumes, what we are looking for is that you are interested in technology or are curious or passionate about it. We don't need you to come in and start writing C++ immediately - that's for the programmers.

We do, however, expect you to come in and start writing English immediately :-)

The VI Road Show

Welcome the newest NI Blog member - the VI Road Show. This is actually a vlog (video blog) that will take you around the country (and possibly world) as the owners showcase NI's employees and customers.

Interview w/April Brinkmeyer

The Austin American-Statesman recently interviewed a co-worker of mine, April Brinkmeyer. She is a technical writer for the LabVIEW core product. Here's a snippet:

Writing, reviewing, updating and improving the program's extensive help documentation in-program, in print and online is an on-going project for Brinkmeyer and the others on the documentation team. She also sits on committees that are tasked with improving help systems across the board and ensuring consistency. Though Brinkmeyer went through an intensive training program and had to learn several new applications, the fact that she is not a programmer or engineer serves her well as a tech writer.

UI, Documentation, and Polish

I'm not sure how it is at other places, but part of being a technical writer at NI is dealing with usability. We are often the first non-engineers/non-developers to see a feature in action. We come across many malformed and confusing dialog boxes, interface widgets, organizational structures, and so on. In LabVIEW we have a great usability advocate in Christina Rogers, who recently made a post about usability and UI. She's also documented many of the UI issues and standards that developers should take into consideration when implementing a feature. Having been present at numerous discussions of "What should this dialog box look like?" I certainly appreciate her work and guidance! She also serves as the arbiter on many UI issues, like, "Should this dialog box button say Close, Finish, or Exit?" It sounds like a trivial question, but as Christina can tell you, issues like these can profoundly affect the user experience and perception of our product.

I bring all this up because of a recent post on Ars Technica about Microsoft's last-minute polish of the Vista UI. Look at the two shots of the dialog box side by side. The Change button is now Rename. The Network ID button is now Join. The text accompanying each button has also been simplified. These are the kinds of changes that we, as technical writers at NI, deal with and have influence over.

(On a side note, you'll notice that I bold the name of buttons you click on -- this is a side effect of writing with NI's company style guide in mind for so long!)

The post about Vista relates to NI in so many ways. Like Windows, LabVIEW is NI's flagship product, the one with the most visibility. Obviously LV is not as big (in market dollars or in lines of code) as Vista, but still. The article's point about last-minute bugs being expensive to fix is a valid one. We have to deal with all those bullet points too, except for the Accessibility one. This is why technical writers are so important in catching/addressing usability issues as early as possible -- the earlier we file a request to change a UI, the less money it costs to fix the issue. At crunch time you have so many people doing so many different things that issues like these often get neglected or deferred in favor of more "Showstopper" issues. Not to mention the overall added stress on the developers during crunch time.

My point is this: an ounce of prevention is worth a pound of cure, right? This is what I tell myself when I file a bug report to a developer over a trivial little issue, like a radio button that should be a checkbox, or a text box that is too short, or a dialog box title bar that doesn't make any sense. This is also what I tell myself when I recompile a .CHM file to rearrange the words in a single sentence, fix one misspelled word, or resize a single image. All these little issues add up to a more professional product that I'm proud of being involved with.

Along the same lines ...

Last month I attended the Austin Game Conference, in which Blizzard VP of Game Design Rob Pardo spoke about Blizzard's legendary "polish," or the overall impression that you're using a well-developed professional product. He said that polish is not something you can just add at the last minute, or even at the last month. It has to be built into the software plan from the beginning. He also said that polish is not just one single thing, like the speed of World of Warcraft's mouse cursor or the shading on the menu bars. Polish is a combination of thousands of little decisions that all get implemented during the development cycle.

This part of his speech stuck with me, because it reminded me of what we tell developers when we hassle them about UI and documentation issues. Sure, in the grand scheme of LabVIEW, nobody cares if a button is labeled Close, Finish, or Exit. They all do the same thing, right? But if we can guide the user on the path they want to take, or anticipate their move and help them make it through intuitive UI design, that adds to the polish. Same with the documentation. No one's going to not buy LabVIEW if we misspell a word in the help. Along the same lines, we've shipped versions of LV that don't include any help for a given feature. I highly doubt that this situation affected sales.

But high-quality UI and documentation adds to the overall presentation of the product and helps users complete their tasks. All the hundreds of little things add up to make LabVIEW a more professional, usable, and complete product.

Bloggers vs. High Schoolers in Writing Competition

/. has a bit this morning about bloggers competing with high schoolers on the SAT essay. If you like, you can even rate the bloggers' submissions yourself!

Here's the essay question, timed at 20 minutes:

Directions: Think carefully about the issue presented in the following excerpt and the assignment below.

I have learned that success is to be measured not so much by the position that one has reached in life as by the obstacles which he has overcome while trying to succeed.'

-- Booker T. Washington

Assignment: What is your opinion on the idea that struggle is a more important measure of success than accomplishment? Plan and write an essay in which you develop your point of view on this issue. Support your position with reasoning and examples taken from your reading, studies, experience, or observations.

Interviewing

Since the day I started at NI, I knew I wanted to be involved in recruiting technical writers. We have a dedicated HR department at NI, but the people you see at career fairs are regular full-time employees. I like this method much better than having recruiters represent us, because I know more about technical writing at NI than the HR people do. Therefore, when students come up to me or I give a presentation, I can answer questions more effectively than someone in HR can. (It's not a "better" skillset, it's just a different one.)

So if you're at a career fair and see an NI booth, you'll likely be speaking with people who actually do the job you're talking about. Sometimes it's a strain on us, because we have actual projects to be working on, and it'd free up a lot of our time if we didn't have to be involved in recruiting. But the end result is worth it. I think our candidates and new employees are of a much higher caliber than they'd be if we didn't see them at all during the interview process.

Last year I did a couple class presentations and visits at UT San Antonio. I also wanted to go to Virginia Tech, but haven't been able to yet. So now I'm one of the three school sponsors for UT Austin. I'm in charge of maintaing our post on AccessUT, which is the job portal from Career Services. I also review resumes, interview candidates in our first round of interviews (there are two rounds), schedule and host candidates for "onsite" interviews (the second round), and pretty soon I'll be at UT's various career fairs for Business, Liberal Arts, and Communications schools.

I like the idea of contributing to NI in a sense other than documentation; recruiting is an additional skillset that makes me a valuable employee. I like meeting and interacting with people, especially new college graduates, which is where we focus the majority of our recruiting efforts. It also helps that I genuinely enjoy NI and my job, so I'm not faking it when I pitch the company to people!

Maybe sometime soon I'll post about what we look for in tech writers, resume tips, interviewing tips, and things like that.

Updates and More

It's been a little while since my last post, so here's what's happening:

• A group of technical writers and I put the finishing touches on A Week in the Life of a Technical Writer. This web site follows 4 technical writers (and 1 manager) through a "typical" week at NI. I say "typical" because there is hardly a typical day here at work :-)
• I got promoted just ahead of my two-year anniversary here, which is great :-) So now I'm a Staff Technical Writer, which probably doesn't mean much to anyone outside the company, but it means that I have an increased set of expectations/responsibilities for my job.
  
• Three of my products released to manufacturing at the same time, which was a bit stressful but otherwise great. It's always a good feeling to get some help files out the door. The stressful part was managing about 10 separate help files as they went through our signoff and verification processes. But that's over now and we're all in the planning phases for the next versions. Work continues on two additional products I'm assigned to.
• I signed up two new LV tech writers to blog here, but they haven't posted yet, so I won't say anything about them until they do.
• I started interviewing candidates for the technical writing position at NI. (Yes, we are hiring! Send in those resumes!)

I also just added a subscription feed for those of you with RSS/Atom readers. The link is on your right, just under the Description of the blog. So now you can read my ramblings without even visiting this site!

Brian Powell, a LabVIEW software engineer with almost 20 years of experience on the team, has joined the blogging crew. Welcome, Brian!

Vlogging

Brian and Colin are putting together a vlog (video blog) for NI Week. They'll be running around the Austin Convention Center all 3 days and capturing most of it on camera. Make sure your hair looks good!

NIWeek 2006

NIWeek is upon us yet again, and it looks like it's going to be fun. If you've been before you know that the keynote speeches and demos are worth getting up at 8 AM for. I've seen several of the keynote demos already, because one is being done by my group, and they're all pretty interesting. Unfortunately I don't think Virginia Tech will be doing a demo like they did last year. However, this year we have Dean Kamen (aka Mr. Segway) speaking, which will be worth attending all by itself. Hopefully we'll also show some more spinning buzzsaws and bouncing ball bearings.

There will be a spot at the LabVIEW Zone on the expo floor that focuses on the NI blogs. Apparently there will also be pictures of the bloggers on the walls; I got my headshot taken a couple weeks ago. It was done in the same secret room where they take all the product pictures for the catalog & website.

If you want to stop by the LV Zone and say hello, I should be around there quite a bit, along with the other bloggers. I promise I won't talk to you about commas and grammar.

You can also be sure that there will be many a mention of LEGO® MINDSTORMS® NXT. This project has been one of the coolest things about working here, and we're finally going to show it to everyone. If you like programmable robots (and who doesn't?) don't miss any of those sessions or demos.

LabVIEW and Music, again

Last December I spoke with the editor of createdigitalmusic.com about using LV + the DSP Module to make some weird noises. A couple weeks ago he emailed me with a question about that post (which actually came from one of our customers), and the answer evolved into this new post about using LabVIEW itself as a sound application. Having just attended the Summer NAMM show here in Austin, I feel the synergy is complete.

Documentation 2.0

Raise your hand: who's heard of Web 2.0? This is the phenomenon that spawned sites like Google, flickr, del.icio.us, Wikipedia, Myspace, and many other "killer apps" for today's Internet. Even Web stalwarts like eBay, Amazon, and Slashdot predicted Web 2.0 long before it existed by making user comments crucial to the site's operation.

There are several discussions as to what Web 2.0 actually is, but the consensus seems to be that Web 2.0 consists of sites that a) run more like applications and b) contain content that is largely defined by users.

Think about Google. How does it provide all the content that it searches? It doesn't; a globe full of Internet users provide the content. And yet Google has stock worth like $380 a share. It provides none of the content; only mechanisms for searching and organizing that content. The same goes for Wikipedia. It falls on the Wikipedia users to provide all the content for the site. Without users, the site is useless. Same with flickr and del.icio.us. Collaboration is the key.

I write about this phenomenon for a couple reasons, but I share it on this blog because Microsoft released their own wiki on MSDN last week. The wiki consists of documentation for Visual Studio and .NET products. Each page is written by Microsoft's technical writers, but because this is a wiki, users can add their own comments to each page.

I really like this idea. I imagine that LabVIEW users know way more about how LV works than the technical writers do. That' s not a slight against my co-workers; rather, it's a recognition of the fact that we are limited by company resources and time. Users, on the other hand, play with a single LabVIEW version for years, while we have to move on the next project once the current one is finished. Not to mention that users actually use LabVIEW. Sure, there are one or two tech writers who can handle G programming, and we all take the LabVIEW Basics courses that NI offers. We use several VIs to help us with our numerous documentation processes. But our focus is on writing, not programming. I'm pretty sure that none of us have developed a test & measurement application.

Imagine if you opened up a user manual and noticed an error in the documentation. Or you notice that, based on your own experience with the product, a key piece of information is missing. If you're dilligent, you send feedback to NI, and a year or so later, you see the corrected material in the new version of the user manual.

Now rewind and imagine opening up that user manual and noticing the error. You log on to your account at ni.com and locate the topic in question (which has been posted online in HTML form). You click the Comment button and post a quick note that details the problem with the topic.

Two days later you receive an RSS notification saying that someone has replied to your comment. It turns out a small engineering company in the Midwest was using the same product incorrectly because the user manual is insufficient or erroneous. But, thanks to your correction, they went in a different direction and the project is moving ahead full steam. Over the next couple days you get several more replies from other users. Some ask questions about your post, and you reply. Some post scenarios where you have to do things differently than the manual describes. Others point out inaccuracies that you yourself had not noticed. A developer explains why certain quirks are present and announces that he's filed a request to change the behavior.

A year later, all pertinent information has been incorporated into the next version of the user manual, and even more people benefit. You gain self-satisfaction and a reputation as a trustworthy expert who knows the inner workings of LabVIEW. Other users gain insight into how to use a particular feature. R&D, sales, and marketing folks gain evidence about how customers use their features. Marketing gains site traffic and credibility. (IT gains another server to handle the load.) Technical writers gain useful, valuable content that trickles down to other users who don't check ni.com. NI gains a positive reputation and tangible financial benefit.

All for nothing.

It could happen, right?

This is how I imagine documentation working, except I don't have to imagine it anymore. What Microsoft has done is create an open environment for users to collaborate based on shared experiences. Similar to Wikipedia, the initiative might expose flaws in their documentation, but I imagine the overall gains (as described above) far outstrip that small setback. They are embracing Web 2.0. And MS isn't alone. Other products have similar functionality for their documentation.

NI has already launched community.ni.com which is a effort to leap into Web 2.0. On this site, users can submit VIs, comment on them, trade tips about them, rate them, and otherwise collaborate. I envision something happening for LabVIEW and other NI documentation.

MarComm vs. TechComm

At my last job, I did a lot of marketing writing in addition to technical writing. This situation arose mainly because my last company had ~25 employees at the time, so we were all required to wear many different hats. Ask me sometime about my adventures in painting the bathroom.

I'd had classes in "professional writing" but no formal training in writing press releases or ad copy, although I did take a class in PR. Yet I found myself drafting these kinds of documents and reviewing them with my boss. What I found especially amusing was inventing quotes that the company president was supposed to have said. I guess up until then I'd assumed that quotes in press releases were, well, real.

It's interesting to me because advertising is seemingly in my blood: my uncle has a long history of corporate marketing positions and is now a freelance marketing consultant. My grandfather was an advertising guru as well, and I have a cousin who's a freelance ad designer (formerly employed at GSD&M).

Marketing might run in my blood but not in my brain. After several PR drafts and other non-tech-writing endeavors, I realized that although I enjoyed the theoretical implications of persuading people to pay attention to my company (with their brains, wallets, or both), I didn't enjoy the actual practice of persuasion. Technical writing suits me much better. I would rather dig deep into how a widget works and explain its operation to people than persuade people that purchasing this widget will solve their problems and make life complete.

As a tech writer, I interact with marketing folks on a regular basis, although perhaps less regularly than some other tech writers working on newer or more established projects. The marketing folk and I come from very different backgrounds but the core is the same: solid and effective communication. It's just that "effective" means something different for each of us. For me, "effective" means "the customer is successful in using the product to meet their needs or solve a problem." For them, "effective" means "the potential customer is made aware of our product and/or turned into an actual customer." Maybe Colin can provide some more insight here.

As much as I am not interested in marketing communication, the disciplines converge when I speak to college students in PR classes (for recruiting purposes). Although these students write all day long, they may not have heard about technical writing as a career option. So I have to do a little marketing communication (presentations, hand-outs, one-on-one chats, etc.) in order to make them aware of the opportunity. Perhaps if I were a better marketer and/or more effective at selling a career in technical writing at NI, we would have gotten a resume or two. As it is, I think we were pitching the wrong product to the wrong audience.

Additionally, sometimes I find myself editing bits and pieces of outbound marketing communication from our marketing people here at NI; typically it's been a little newsletter blurb about one of our product releases. The markeing people are not required to use us as editors as they have a different style that we do, but sometimes it might help a new or transitioning marketing person to get the tech writer's perspective. In these situations, I really have to hold myself back from going overboard with the red pen (virtual or real) and remind myself of the differences between marcomm and techcomm.

Whether you're communicating what a product's features are, or communicating how to use those features, both jobs come down to the same base: effective communication that achieves the goals you want.

Changing Expectations

I've been working at NI for a little over a year now, and I'm beginning to realize that working for this documentation team has raised my expectations any time I hit a Help button in any program. Raised my expectations to my benefit and aggravation!

The truth is, not every company that writes software has the ability to, or the willingness to, create a comprehensive Help like I think we do at NI. Tooting my own horn? Maybe a little. But even though we haven't produced a "perfect Help" for LabVIEW yet, we have a lot of folks here working hard every day to improve the supporting documentation in usability, scope, and detail. We're definitely some of the best Help I've seen.

On the other hand, just as I've learned to click the Help button in other programs expecting answers to my questions, I think a lot of other people have learned NOT to click the Help button in LabVIEW. Their expectations are that they won't find answers in the LabVIEW Help because they've been disappointed so many times before with other help systems.

In fact, today we had a tech support person bring us a printed copy of a web page with a topic that he said should go in the LabVIEW Help because it was so useful to the customer. Turns out, he'd printed a topic from the LabVIEW Help we just recently posted to the Web!

Funny. Frustrating. The incident might say more about people's comfort level with the Web as the ultimate documentation resource than about their confidence in the LabVIEW Help. Then again, it might also show that we need to continue marketing our own Help - even within the company.

I'd be curious to read more examples of great online help. Suggestions, anyone? I've got a list as long as my arm with bad examples...

It's Not All Pencils and Paper

One reason I enjoy being a technical writer at NI is that we don't just write stuff and draw squiggly editing marks on other people's papers. True, that is some of it. But beyond the writing and editing, we are allowed (and encouraged!) to suggest and implement improvements to the software.

For example, all LabVIEW's VI/function help topics contain buttons labeled Place on the block diagram and Find on the Functions palette. Clicking these buttons opens an interactive pathway between the help file and LabVIEW itself. The idea for buttons like these originated with the LabVIEW technical writers. They saw a need, proposed a solution, follwed through, and the rest is history.

I recently proposed, and am in the middle of implementing, two help system improvements of my own. They both deal with LabVIEW MathScript and the way users interact with help in that environment. I was pretty nervous when it came time to present these proposals to the appropriate people because I'd never done this before. We all sat down in a brainstorming meeting to discuss the merits of my proposal. I started off basically by saying "Tell me what I did wrong." I was worried that I'd proposed some fatal flaw that would get my proposal rejected, or that I'd get the dreaded "That's great Ryan, but we don't have enough time to do this." But none of that happened.

That meeting was an eye-opening experience for sure. Now that I have that under my belt, I am moving forward with getting my idea actually implemented in software. It's pretty neat to see a checkbox there just because I asked for it (and several people approved it, of course). Oh, that sounds so geeky. But it's true.

I'm talking only about the two ideas I proposed, but I've watched several other LabVIEW technical writers, who are newer here than I am, have come up with other awesome ideas for the help system. These features improve the user's ability to submit feedback on our help files, scan and navigate a long help topic, and find what they're looking for in the index. I really think these features will add value to LabVIEW.

An interesting side effect of this process is that we get mini-tutorials in project management. We propose the feature, figure out how to (and who will) implement it, delegate tasks, manage resources and deadlines, and see everything through to completion. This is the norm for a developer or project manager, for but a technical writer? It's pretty cool. At least it is to me :-)

Sure, we might not impact a customer's life as much as if the developers decide to add a new ODE solver or signal window to the palette. But I can point to a particular feature and say "I thought of that and made it happen in reality."

A lot of software developers I know (both here and elsewhere) have expressed interest in designing/coding video games. In fact, that's originally why I entered college as a Comp Sci major. As a parallel, I wonder if any technical writers secretly dream of writing strategy guides.

How do I turn this thing on?

I caught the following passages over at HardOCP this morning. The quote comes from a review of the Voodoo ARIA Home Theater PC (HTPC). Although the product is a Windows-based computer, the outer case and presentation to the user is drastically different from a typical PC.

One thing that I mentioned earlier was the extreme lack of documentation on the Voodoo PC ARIA. Granted, it’s a new product for Voodoo, but we spent a small fortune on this system and I was actually scared when I first pulled it out and realized I had no idea how I was going to use this system in conjunction with my entertainment center. My perception of value had dropped significantly. Heck, my $250 Panasonic DVD player has a 100% complete manual that explains every single nuance of every single function you could possibly use.

I didn’t even have the first bit of information regarding how to use Windows Media Center Edition – so I did what any guy would do – I hooked it up and started pressing buttons.

It took me a good hour to figure out how to get a properly sized video signal to my TV, so I figured that it would be a perfect question for Voodoo to answer.

... My point of contact for anything I needed was with my sales representative, Lance. Lance and I exchanged a couple dozen emails and phone calls, many instigated by him and inquiring to how my system was doing. That calmed many of my fears about being stranded.

Lance got me in touch with their technical support department and I was quickly assisted by their knowledgeable staff in setting up the ARIA to not only interface properly with my HDTV, but to be sure that my Audigy 2 ZS was properly configured.

I also received updated documents on the ARIA’s functionality that I hope will be included in future ARIA sales – they were certainly things I would have liked to know out of the box.

The emphasis is mine. I wonder: how many users end up not finding what they want in the LabVIEW documentation and then reduce their opinion of our product? Is there anything we can do about this?

Coincidentally there is an ongoing thread on the Dev Zone about how users best learn LabVIEW. It's interesting to see some of the comments there regarding the documentation. Because we (tech writers) don't deal with customers on a daily basis, it can be a little unnerving to hear their unbiased opinions about our work! But all feedback is helpful and (given the proper resources and time) will lead to improvements. This thread is an opportunity to get some interesting data points and scenarios from actual customers, which is great. We're also working on ways to give customers a more direct way to comment on the documentation.

How Do You Do That Again?

We consistently get feedback from our customers that the example VIs we ship with LabVIEW are really helpful. The developers put a lot of time and effort into creating examples that demonstrate new features and show how to accomplish certain tasks using LabVIEW. In addition, the examples serve as great templates for certain common applications. For example, if you want to acquire a measurement from a DAQ device, perform some measurements and signal processing on the measurement, and display the results in a plot while simultaneously writing data to a file for later use, we ship example VIs that do just that (I think; don't quote me on that :-). So you don't have to go through the trouble of digging through our help files to figure out how to daisy-chain these VIs together. We've done the majority of the work for you.

The Control Design Toolkit is a great example of how to create, well, examples :-) We categorize all the examples into separate .llb files, one for each palette. Coincidentally (or not!) each user manual chapter corresponds to a palette. So for the upcoming release, when I was trying to find a way to highlight the examples, I simply added a canned statement to the beginning of each chapter that refers the user to a particular .llb. Because we structured the examples so well from the ground up, each example .llb maps to a chapter, and I made the connection pretty easily.

The examples serve as a great connection between the tech writer and the developers. The developers create the examples and document them by adding block diagram/front panel comments and a VI description that shows up in the Example Finder. So in this sense, the developer "owns" the example. But as a tech writer, my responsibility is to make sure the descriptions are accurate and helpful. So yesterday I just finished scrubbing all the descriptions for each example. It was a good long effort, but it pays off when customers tell us how easy it is to use the product, because all they do is open a example and go to work.

Another product I work on recently received some feedback that the examples could be even more useful if they were not so complicated. This is another issue that crops up also in documentation - how complex is too complex? In this case, a professor was teaching his students the fundamental concepts that our product demonstrates, and the shipping examples were too high-level to be of much use because there are so many functions contained in each. He suggested simpler examples, with just an input, the function, and some output. This way his students could see the operation of a particular function without the "noise" of having so many other functions and wires around.

We talked about this feedback for awhile and decided it was worth it, for the upcoming product, to develop these "basic" shipping examples to demonstrate the purpose/functionality of almost every function we ship. It'll take a bit of time to do well, but the result will be a less-intimidating product that will be of more use to everyone.

So now we have a split between 1) providing pre-written programs and 2) demonstrating how to use the product to do what you want. These requirements are not mutually exclusive, but it can be hard to design a good example for both requirements. Oftentimes, as in the case of the aforementioned product, the examples are wonderful at The Control Design examples are split into two directories: Getting Started (which has the .llb files organized by palette) and Case Studies. We want users to look in the Getting Started directory to become familiar with the concepts of the product: how to analyze a Bode plot, how to discretize a PID controller, and so on. The Case Studies are not necessarily prebuilt applications, but they take a more in-depth look at the toolkit by, say, designing a controller for a hard drive's read/write head within certain constraints.

LabVIEW includes a tool called the NI Example Finder, which you can access by launching LabVIEW and selecting Help»Find Examples from the pull-down menu. If you get stuck, try playing around with this window and seeing what you find. I bet you'll find some useful applications just sitting there, waiting to be developed. Each module and toolkit, as well as some hardware, also ships some examples with their software. Check them out and see what you come up with.

I'm taking more opportunities to suggest examples and make sure they are well-documented. In addition to example VIs, we're always looking for ways shrink the "installation-to-usage" time that measures how quickly a user can *use* the product after installing it. We've been coming up with some great ideas, some of which I hope to implement in the coming months.