What features are self-evident? What features really need documentation? If a feature does need documentation, how much documentation does it need and what level of prominence should a feature have? These are questions I have to ask myself many times throughout a document's life cycle.

During the planning phase of development, it's my job to gather the proposed features together and determine how each one will impact the documentation set. For example, Feature X might require updates to the online help, a bullet point in the readme.html file, a new graphic on page 11-3 of the user manual, and revisions to existing paragraphs that are related to the new feature. To determine the documentation impact, I talk with the developers and ask them what users need to know about the feature. From that, I can get an idea of where a feature needs to be mentioned. As the feature morphs from planning to implementation, the documentation is inevitably affected, and I have to stay alert to see what's going on.

Sometimes I immediately think that a certain feature, UI change, or other small tweak does not need any documentation. This is especially true when I use a specific term while explaining the operation of a function or dialog box. It's standard practice to ask the developer if I can expect a user to know, for example, what rate-monotonic scheduling is. But a lot of the time it comes down to what I think the users needs to know. I realized the other day that I make decisions like these all the time, and I'm effectively imposing my personal biases, assumptions, and viewpoints on the user. I'm basically saying "Oh, anyone can figure this out, it's pretty self-explanatory." Is that really the case, though? I'm not sure there's a definitive answer to that question.

For one thing, I can never be sure who's going to use my products. (I say "my" like I own it somehow, but you know what I mean.) Some engineering firm might have an in-house LabVIEW developer who knows how to operate the Simulation Module by heart. But if this person is out for a week, or quits, their work might get passed off to someone who's never seen the product before. Or there might be a division of labor scenario where one person acquires a plant model, another designs the controller, another designs the simulation, another implements everything on a real-time target, etc. In these situations, taking the time to explain certain terms, phrases, or features can (hopefully) help the next person in line do their job better.

Another consideration in deciding what's obvious or not is the layout of the UI. After watching people test one of my products, I noticed that the order of buttons on a dialog box can have a big impact on whether or not a user can easily accomplish a certain task. Even something as seemingly insignificant as a button label can help users step through a task. Fortunately, as tech writers at NI we’re encouraged to suggest alternative methods of dialog box layout and navigation. We step back from the product, clear our heads of everything we know about it, and act like a first-time user who knows what they want to accomplish with the product but is unfamiliar with its layout and/or operation. In fact, a suggestion I had for the Simulation Interface Toolkit will end up being a feature at some point.

Anyway, the first point of contact is the developers, who can tell me how they want a user to use the feature. As I said before, they can also tell me about any industry-standard terminology. The other LabVIEW tech writers are definitely another resource, since most of them have been working on LabVIEW and/or its add-ons for quite some time now. A lot of times, I or another writer will cite precedent and consider the issue closed.

We work closely with the product support engineers, who in turn work closely with customers, to find out whether a certain explanation or feature might be helpful. The style guides to which I adhere also contain information on issues like these. Finally, I’ve found that interns / co-ops can have some useful insights into products they haven’t used before.

If none of these resources produce any solid case for or against the documentation or explanation of a piece of information, the decision lies with me, and that’s where my own worldview comes in to play. And while I’m not pretending it’s a giant weight on my shoulders, the fact is that I’m the main gatekeeper for what users see in terms of help for a particular product. That is, if they read the help in the first place :-) As I gain more experience with the Control Design & Simulation products and the ways in which the users like to accomplish tasks with these products, I'll be able to make more informed judgement calls on the level of documentation / explanation for a particular feature.

Ultimately, I suppose, the goal is to design software with features so intuitive they don’t require any documentation. If that ever happens, though, I suppose I'd be out of a job :-)