December 27, 2007
Through a co-worker's blog, I came across a post about sitting near your SME at the office. I cannot agree more emphatically. At NI, most of technical writers sit in the same general location as the engineers for whom they write documentation. For most of my three years here, I could swivel my chair 360 degrees and have a direct line of sight to all of my engineers.
I strongly believe that this proximity is key to establishing quality documentation. When the barrier to interaction is low, you are more likely to ask SMEs questions. If you have follow-up questions, you don't have to wait for these follow-ups to percolate through the developer's email inbox -- you can walk over to their cube and have a discussion. The developers are more likely to take your presence and schedule into account - meaning, if the release date slips or if they decide to add six new features, it's easier for them to inform you in person (where, again, you can ask follow-up questions on the spot). Because they don't have to work as hard to tell you about these changes, they're more likely to tell you. You're also more likely to socialize casually in the office, an action that improves interpersonal communication in general.
Phones and email and instant messaging are wonderful and great ways to assist technical writers. But oftentimes there's no substitute for face-to-face communication. Especially not when you're trying to ascertain the finer points of model predictive control :-)
So for all of my time at NI, I've enjoyed these benefits. This situation changed last year when I wrote the documentation for MATRIXx 8.0. During that project, I had to be aware of a small time-zone difference when calling and emailing my engineers. This was only a problem early in the morning and at lunch :-) To ease the pain, we had numerous conference calls, and in 2006 I even spent two weeks at their office so I could better understand the product during its development.
But at least my developers were in the office at the same time I was. This situation changed even more drastically when I begun working with developers in other countries. At this point you're introduced to the fascinating world of late-night (or early-morning) conference calls, reviewing & commenting on documents electronically, and never actually meeting the people you're working with. Add in language considerations, and you have a whole other ball game.
I wouldn't say that this distance decreases the quality of the documentation. However I would say that you don't get as many chances, or you have to work extra-hard, to keep the quality of the documentation consistent with what you've been doing locally. For example, consider this situation:
I email a developer in our Shanghai office at 3 PM CST. They don't get the email until 8 PM CST (9 AM their time). At this point I'm obviously not at work. I don't get their reply until 9 AM the following morning. This email has made its round trip in 18 hours. Compare that to 2 hours or less for a typical email to someone in Austin, or even California.
This fact underscores the importance of being precise when you're corresponding remotely. What if I have follow-up questions, or need clarification, to my Chinese co-worker's reply? I send this hypothetical follow-up email at 10 AM. Then it's another 23 hours until I get all of my information.
Total time for information flow: 41 hours. That's almost two days during which I am stuck on a problem or unable to do my job. And I'm assuming here that the developer actually has time to answer my question during their workday. If not, add another 24 hours onto the cycle.
I see a couple ways to mitigate this issue. One, be as detailed and precise as possible when emailing remotely. Treat your co-worker as an audience of one. Anticipate questions they might have and answer them in advance. Two, you can stay up late or get up early so that you're both in the office at the same time. Three, and this is the most effective measure, try not to rely on remote locations for decisions or information. (I know, I know -- easier said than done!) The finer points of this solution include making every use of local resources. You could spread knowledge around so that no one person solely is dependent on any other person (we also like to call this the "hit by a bus" defense). Four, and this is the most fun measure (at least for me), travel to the remote office and spend some time there :-)
(I just realized that the above paragraph probably should be a bulleted list.)
This situation obviously isn't unique to technical writing. These intercontinental concerns happen also with software development, upper-level management decisions, and technical support. Thankfully, at least in my case, you could get some fantastic travel opportunities out of this way of working. Which is my own very subtle way of segueing into the fact that I will be living and working in Shanghai for at least the first half of 2008. I leave in one week. I look forward to posting about my international technical writing experiences :-)
November 27, 2007
...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.
...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.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?
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.
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.
August 3, 2007
File this one under "Coolest Things I've Ever Seen." Vineet samples himself beatboxing and singing. He can do this multiple times until he is giving himself a full backing melody.
Watch this one to see Vineet turn it up a notch!
Try doing that with an oscilloscope!
August 2, 2007
Date / Time: Wednesday August 8th, 3:30 PM. Room 16A.
Title: Documentation Dividends: Help that Pays Off
Abstract: Well-planned product documentation can save time, reduce customer frustration, and improve your product’s reputation. Discover how LabVIEW can help you create and deliver effective documentation. Also learn tips from NI technical writers about optimizing the documentation process and getting the most out of documentation on LabVIEW.
Come learn how documentation can improve your product. We'll also discuss tips for planning and creating documentation and the different ways in which you can deliver documentation.
I invite you all to attend, and if you have any questions or comments for me, I'll be happy to answer them at the session.
June 28, 2007
- Your source files are stored in a repository on a central server.
- To edit a source file, you must "check out" the file. Checking out a file downloads a copy to your computer, where you then make your edits. Typically, checked-out files are marked as such so others cannot check them out at the same time.
- When you are done making edits, you check the file back in, which involves uploading it back into the central repository. Others can then synchronize to the latest version of the file that contains your edits, check out the file themselves, and repeat the process.
- Because only one person can check out a file at a time, SCC ensures you don't overwrite ("blap") edits that someone else made. This benefit mainly is for larger groups of writers that all work on the same source material, like in LabVIEW.
- Because the most recent copy of the file is stored in a central location, everyone knows where to go to get the freshest copy of all necessary files. Again, this benefit mainly applies to groups of technical writers.
- Ensuring you have the latest version of a file is as simple as right-clicking a file and selecting Sync to latest revision.
- SCC allows you rewind time back to when a file was good. If you check a file in and suddenly the XML won't transform or the HTML looks wonky, you can synchronize to a previous revision of the document when you know everything was good. The SCC program can handle this revision history automatically, so you don't need to spend time renaming files, copying files to different directories, or marking files as read-only.
- Some SCC programs feature an integrated tool for differentiating ("diffing") between versions of files. With the click of a button you can highlight differences between the document you're editing and what's stored on the server. This tool is really powerful for documentation because you can see exactly what changes someone else might have made to your document. (Or, if you're a lone writer, what changes you made to your document!) Because the changes are highlighted onscreen, you're not distracted by unchanged text.
- SCC allows you to annotate the changes you made every time you check in a file. These annotations can be as simple as "Fixed some typos," but more descriptive annotations are even more helpful. By clicking "Revision history" in Perforce, the SCC program NI uses, I can see who's done what to the file. Some file histories extend back to 2001 and provide a rich timeline of the file's evolution over time. This benefit helps not only large groups of writers, but even lone writers who want a quick record of what they've changed and when.
I find that the only drawback with SCC is the overhead of editing a single file, which involves the following steps:
- Launching Perforce. (Actually, I usually keep it running.)
- Navigating to the file's place in the repository. (This can be slightly time-consuming if the server is being slow, the file is located on a different server, or if the file is buried in a deep directory structure.)
- Checking out the file.
- Launching the program to edit the file.
- Editing the file.
- Saving the file.
- Using Perforce to annotate the changes you've made.
- Submitting the file.
Also, it can get confusing if you sync to a file and then delete it by using Windows Explorer. In this situation, the SCC program still thinks you have the latest copy of the file, so you have to remember to force the program to actually download the file again. But this is really more of a "user error" issue, although it crops up for me frequently as I install and uninstall various development versions of LabVIEW on my computer.
For those of you who want to give SCC a try without spending a dime, check out subversion or the Perforce evaluation.
June 8, 2007
Interested in working as a technical writer but don't know what it is that we do? Our Texas Tech recruiting team gathered some alumni and put together an informative video that consists of interviews with technical writers and managers here at NI. The video also has some great tips for those who are applying for technical writing jobs. Top tip: Proofread your resume! :-)
May 25, 2007
Before I came to NI, I'd write a sentence like this:
You can also double-click the Add function.
But now I write like this:
You also can double-click the Add function.
You must manually specify the value.
You must specify the value manually.
See the differences? I had no idea that people wrote things like "also can" until I started at NI. And I disagree with the way it sounds and looks. (At least, for the first example. I can understand the way we rewrite the second one.) But since then I've noticed many other publications, such as the ESPN Magazine, do the same thing. I guess my brain had skipped over this construction before, but now that I actually have to write this way, I notice it more.
When I had the chance to write the documentation for MATRIXx 8.0, I decided against using this guideline. I just think it looks/sounds weird. But when I switched back to LabVIEW-based products, I had to ease back into using this construction again. Every time I start writing "can also," it's like I have to flip my brain around. I'm getting used to it again. I still think it looks weird and don't like using it. But now that I've seen other places use it, maybe I don't mind it so much.
I know some people don't care about verb-splitting, but others really enforce the "rule" against it. Our company-wide style guide is a communal effort that involves input from all the technical writing product groups. At least one time that I know of, we've voted to remove the restriction on splitting verbs. But even though the company style guide might say this, the product-specific style guide (which is our first point of reference) might disagree. Even if that isn't the case, your manager who reviews your content might not want the verbs split.
Anyway, just some random commentary on something that I find odd :-)
May 16, 2007
It's an interesting idea for official NI documentation, too. For example, see the MSDN wiki that I posted about a year ago. It's good to see this kind of thing spring up organically among customers.
May 11, 2007
Supposedly, the optimal format is a series of "short, cascading phrases" that look really odd but are easier for the human brain to comprehend. Of course, Walker Research makes a product that reformats text in this manner automatically :-) Apparently the company has improved some test scores by simply putting tests in this new format. A major textbook publisher also has contracted Walker Research for help with online textbooks.
I'm skeptical about company-conducted research that conveniently provides an excuse for purchasing a product from the same company. But the theory is still interesting. NI does a lot of documentation "online," meaning shipped as HTML. And the very essence of our jobs depends on readers comprehending the material. Maybe this new theory means we'll someday
be writing documentation
Edit: A link to the ensuing Slashdot discussion.
January 11, 2007
In this next series of posts, I'm going to cover the various ways in which you can access the LabVIEW Help from inside and outside the software itself. Here's the most general way.
Start>>All Programs>>National Instruments>>Labview xx: Going here shows you three useful entries: LabVIEW Help, LabVIEW Manuals, and Readme. The first link opens lvhelp.chm, which is located in the labview\help\ directory. ( where labview is the directory to which you installed LV.)
This help file is the gateway to just about anything you could want to find in the LabVIEW Help. Starting with LabVIEW 8, the technical writers made a decision to stop splitting content into PDF and HTML source. We decided to make (nearly) every topic available from within the HTML-based LabVIEW Help. We kept a couple of PDF and printed manuals, but who knows how long those will last? (The switching process itself was large, complex, and often painful. Maybe that's a subject for another post.)
The LabVIEW Help is modular and extensible. We use Microsoft's HTMLHelp framework (and FAR to do all the work of compiling and managing settings). Every time you install a LabVIEW add-on, such as the LabVIEW Real-Time Module or the LabVIEW Simulation Interface Toolkit, another book (or, more likely, several books) appears in the LabVIEW Help's table of contents. So whether you're looking for help on an FPGA topic or for information about the Control Design Construct State-Space Model VI, the LabVIEW help is your one-stop shop.
In fact, the lvhelp.chm file itself is mostly a reference to other install .chm files. For example, in the labview\help\ directory, glang.chm contains most of the VI & function reference information. glang = G Language, get it? :-)
lvhelp.chm "includes" both of these files (and many more), so the lvhelp.chm file itself contains very little content -- mostly just the legal and high-level organization topics.
The second link takes you to the labview\manuals\ directory. If LabVIEW or an add-on installs PDF manuals, those manuals will show up in this directory. Because of the aforementioned shift to HTML-based documentation, not too many add-ons use this folder. LabVIEW itself does, and two of my products (the Control Design Toolkit and the PID Control Toolkit) still install PDF manuals here. But products like RT and FPGA produce almost no PDF documentation anymore.
PDFs come and go all the time. For example, in the Simulation Module 2.0 release, we shipped a PDF manual. For the subsequent release, Simulation Module 8.20 (the version number jumped up to be consistent with LabVIEW's), I converted the PDF into HTML (like magic!). Some other groups in NI are doing the reverse; going from HTML documentation to PDF and/or printed documentation. It's all based on what works best for the customer.
The third link is to the labview\readme\ folder. I'm pretty sure that all LV add-ons install readme.html files, and these files get placed into this folder. (Of course the files are all named differently so they don't overwrite one another.) Readmes typically contain installation instructions (because the readmes are visible on the top level of the installation CD), information about new features, bug fixes from previous versions, last-minute documentation updates, and known issues with the current version. However, the presence or absence of this information differs from product to product, even among LabVIEW and its add-ons. In addition, some developers prefer to write their own readmes, whereas some prefer to hand off the readmes to us technical writers.
January 8, 2007
Austin-based Whole Foods ranked #5. Go Austin!!!
Another funny tidbit is that Texas Instruments (TI), the company for whom NI is most often mistaken (don't worry, I did it too), is listed right below us.
Who is #1? Of course, that spot belongs to the six-million-dollar-a-share GOOG. I have to say though that free spa treatments would not necessarily attract me to a company. Free meals, however, are a different story :-)