It's Been Awhile ...

...but I wanted to link to two posts I saw on the User Advocacy blog:

Technical Writing in Transition: Part 1 and Part 2.

Makes for some interesting reading, I think.

Quote:

Technical writing has adapted with three fundamental changes:

1. Task-oriented writing. Instead of describing the parts of a system, we walk the user through tasks and explain technical knowledge incidentally.
2. Single-sourcing. Write-once, read many; we write in small blobs which can be reorganized for online help, web help, printed manuals or marketing.
3. Plain English/Simplified text. We describe the interface, not theory, using code-like patterns of if-then language and action sequences.

And this:

...to a public increasingly acquainted with the similarities between computer-based tasks, [writing a fantastic manual] does not provide the depth of information they need, so instead they buy third-party "power user" books to fill that need.

...

When the basics of technology are known, it is easier and cheaper to have an engineer type up notes and hire a college student to format them.

I can see how this statement applies to consumer electronics like digital cameras, MP3 players, etc. Those are situations where "the basics of technology are known." Has anyone looked at the user manual for their iPod?

However, I don't think this statement applies to LabVIEW, where the basics are not known -- except to those who've been using it for years, and even then, those people still get some surprises now and then.

So that's the key phrase -- "when the basics of technology are known." That is not always the case, especially not at a company like NI. You could argue that the "basic" of LabVIEW is dataflow programming (and possibly graphical programming also). Everything on top of that is LabVIEW-specific and needs to be explained in detail in our help system. And given that we fight for dataflow attention in a sequential world, I would say that we still need to teach people the basics of dataflow in our manuals (which we do). And that can get complicated pretty quickly.

Extend now to products like the Control Design and Simulation Module. Here the "basics" become control theory, dynamic systems, etc. These topics are the subject of graduate- and doctorate- level courses and degrees. While you could ask the engineers to educate users on these topics - with formatting assistance from a college student - the results would be geared towards graduate- and doctorate- level customers, which is not necessarily our audience. Plus, it's a well-known fact that many engineers either dislike writing or don't care that they're not good at it :-)

LV's also more complex than many software programs because it's not really a program - it's a programming language. Covering the limitless ways in which you can use LabVIEW is a, well, limitless task :-)

It's like if I were to document a toolbox full of wrenches, screwdrivers, drill bits, and such. I can tell you the purpose for each tool, what types of situations each tool are good for, and maybe give you some high-level examples. But I can't go specifically into how to use the wrench with a car, sink, light fixture, two-story house, lawnmower, etc. That would take way too much time and way too many resources, especially when you realize that I'd have to describe how every tool works with every task. But here also the manual would be incomplete, because how can I know what tasks you're going to use these tools for? Maybe you like building birdhouses, but we don't talk about that because we don't have a birdhouse expert on staff. So then you're still out of luck with just our user manual.

No, the specifics are things you have to learn by taking the groundwork in the manual and applying it to your project. Or, like the quote says, you might go out and buy a book on fixing cars, or even more niche, Using Wrenches with Cars. That's where companies like O'Reilly and Wiley come in. That's also where customers, blogs, and user forums and communities help fill in the gaps. We constantly monitor these sources of information, looking for real-world problems and successes that we can include in the documentation. By "we" I mean not only technical writers, but also engineers, salespeople, marketing, etc.

(As a side note, I think we do a great job of covering LV-based tasks in our help files. We make sure to include tons of how-to content in our docs.)

I'm sure the author of those posts didn't intend to mean that all technical writing is basic and therefore we can just outsource everything to college interns. But I thought a counter-example would be useful and informative.