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 :-)
  
  
  

Asking Questions is Key

I think one of the hardest things in technical writing, especially for new hires, is to be assigned to document a product or feature that you know nothing about. Since we have a wide variety of LabVIEW products, from signal processing to HMI to control and simulation to report generation to sound and vibration measurements (not to mention the core product itself), no one can be expected to understand the minutiae of them all. And yet our writer who works on a Control Design product might be asked to edit another writer who is working for an HMI product. Or the signal processing writer might leave and the HMI writer might be asked to fill in until we can find a replacement.

Whew. That's a lot of stuff to cover. But we're not engineers. Some of us have a technical/mathematical/scientific background, sure, but many of us are English or Tech Comm majors. How do you write help for a product you know nothing about?

Well the answer is: you learn. You do this primarily by working with Subject Matter Experts (SMEs) who, here, are the engineers who develop these products. They are the ones who have not only the domain expertise (like advanced degrees in the aforementioned disciplines), but also the LabVIEW programming knowledge to help you write documentation.

Still, it can be daunting to read a feature spec and not know where to begin. That's why I believe one of the most important skills a technical writer can have is knowing how to ask questions. (There's a reason we have several Journalism majors who work here.) Questions about functionality, background reasoning, implementation, usefulness, future features, and so on. Questions that nitpick and dig into what the developer really meant when he said "if necessary". These are all fair game in determining a starting point, an outline, for writing documentation. And once you have that outline, you're in far better shape than you were before, because you have a plan of attack. Even if you initially knew nothing about the feature.

Of course, it's a chicken-and-egg problem. You can't ask questions if you don't know enough about the feature to know what questions to ask! That's why, on the LV Doc team, we've developed a list of questions to help writers, especially new ones, get started writing about unfamiliar features. That's why research with the developers can be so valuable. Even if you don't know what they're talking about, you can pick out patterns, keywords, and things to ask questions about later.

That's why we look for writers who are geeks, who love learning technical information. We don't ask you to be a computer scientist when you join NI. But if you're going to write for (as an example) LabVIEW, you'd better get a thrill out of learning about object-oriented programming, data types, and 3D graphs. Otherwise you're going to hate it here, which is a situation nobody wants :-)

Over time you develop patterns of behavior that proves successful in giving you a sufficient amount of information about a product in a short amount of time. And then when you're asked to pitch in on another product, you aren't afraid anymore. You trust yourself to be able to obtain the knowledge you need in order to do your job well.