Musings

Well the holidays are upon us, so most of the office is empty. One product of mine is nearing the beta phase, so I've been consolidating the documentation into the installer build. What's in there now is definitely good enough for beta, and really only has a few issues. The interesting (perhaps troubling) thing is that our document review process requires certain steps to be taken after beta. This means that while the developers can front-load a lot of their work before beta (which is a good thing, don't get me wrong :-)), I have to wait until after beta to move the review process past a certain point. So in that sense it's like "hurry up and wait!" This situation makes sense though, because we don't want to get the documentation into its final stages before beta ships. We often integrate a lot of customer feedback during the beta program, as any good software company should, and a lot of that feedback changes the documentation. So our almost-final signoff phase is reserved for after beta. In this case though, there might not be that big a window between beta shipment and product shipment. So while the documentation might be in decent shape, there's still several more review processes I might have to cram into a short amount of time.

In addition to all this, work is beginning on a completely new (version 1.0) product. I've been assigned to the documentation and I'm having fun learning about what the product does and how it serves customers. Documenting a 1.0 product is an interesting challenge I've watched several other LV tech writers take. You get to be in on the ground floor, and if you're good, you're able to shape the terminology and how people think/talk about the product features. The usability feedback us tech writers provide also comes into play at this early stage, when all we have go to on are screenshots of dialog boxes and stuff like that.

This evening, I'm flying back to Maryland to visit my family. Happy new year, all!

New String Functions

In my role as part of the LabVIEW documentation team, I use LabVIEW a lot, but often not the way the typical user would. Though I have some NI hardware installed, I rarely acquire, analyze, or present a signal. I use it mainly for… string manipulation. You read right. I use LabVIEW for string manipulation – searching, splitting, and replacing text. Historically, this is not one of LabVIEW’s strengths.
My VIs have a lot of string functions, each handling some specific string manipulating operation – one that splits the string, another that splits the remaining string, one that searches the resulting string of the previous two splits, etc. Also, I’m reading files, moving files around, changing file permissions, taking strings from one file and moving it to another file IF something in the string matches something else, etc. I use a lot of For Loops and a lot of While Loops with shift registers that I get the stop condition wrong on half the time. I’m sure there are ways I could make my VIs more streamline, but I’ve been doing things the same way for so many years, I’m just sort of stuck in my LabVIEW coding ways. Right now my block diagrams look like Jackson Pollack paintings.
So, now, 8.0 is out the door (of course, I had to use 7.1 to develop tools used to document 8.0) and I’m thinking to myself, maybe it’s time to teach this old dog some new tricks. What’s 8.0 got to improve string parsing and file I/O? I was in for a very pleasant surprise.
First, there’s this function called the Match Regular Expression function. I used it the other day for the first time for real (not like when I’m writing documentation for a feature, which is when I try and come up with the most ridiculous use case I can come up with that may or may not have a correlation in the real world, just so I can understand the intricacies of the feature).
So, right away I’m using a single function to parse the data from a whole text file. No searching and splitting functions. No While Loop with shift registers that I need figure out the stop condition for; just a single function with four wires. The magic is this function uses Perl-like syntax. In fact, it talks to an open-source Perl library developed at Cornell. I know next-to-no Perl script, but within minutes I was using this function exactly as I wanted to.
Second, the File I/O VIs are no longer VIs. They’re functions – nifty polymorphic functions. I can’t tell you how many times I’ve had to replace the “Read Characters from File” VI with the Open and Read File functions because I need to work with a File I/O function that only accepts a refnum for some other reason later in my data flow. Those days are over because most of the File I/O functions accept refnums and path names.
Yes, I could try and go home and relay this epiphany to my family around the dinner table, but I’m not it would meet with much enthusiasm (especially from my kids – ages 2 years and six months). This forum seemed the best place to share my enthusiasm.

Combining Work and Fun

Being a digital music aficionado, I read Createdigitalmusic every day (several times a day, actually). I submitted a news article the other day, and what do you know, it relates to LabVIEW!

Who Writes Here

Edited 1/23/2009 by Ryan:

I'm really the only person posting to this blog now, so I've removed the information about the other people. I also updated my information.

Ryan Pollack (Staff Technical Writer)—I've been working as a technical writer/supervisor at National Instruments for over four years. Currently I design, write, and edit documentation for the LabVIEW FPGA and Real-Time Modules. I also supervise other technical writers for these products.

I graduated Virginia Tech in 2003 with a BA in Interdisciplinary Studies. I spent all of 2008 living and working in Shanghai, China. In my spare time I improve my photography skills, create electronic music, write articles for several local/national magazines, stay current on technology trends, and enjoy the wonderful city of Austin.

Context Help & Super Tooltips

In LabVIEW, we have this fun feature called Context Help. The CH window updates whenever you move the mouse cursor over an object, such as a VI, wire, dialog box component, property node, and so on. The functionality is similar to "tooltips," which appear in many programs including LabVIEW. These are the little bubbles/blurbs that appear when you move your mouse cursor over, say, the Insert Table button in MS Word.

I just read an article saying the next version of Office 12 will support extended, or "super," tooltips. The idea is to "give you the idea of what a feature is for without needing to look it up in help or in a manual," according to the head of MS's User Experience team. Traditionally, tooltips have not been very expository. They show only the name of the button. These super tooltips bring those pop-up bubbles in line with our Context Help window, which can display quite a bit of text (and even a picture of the VI).

Another interesting tidbit is the way they structure the Super Tooltip phrase. The phrase completes the sentence "This is the right feature to use if you want to ___________." Our CH phrases always start with an action verb, such as "Generates," "Calculates," "Returns," "Implements," or something along those lines. Basically it's like a present-tense version of a resume :-) I'd be interested in hearing the reasoning behind the decision to use that phrase.

Another similarity: when a super tooltip is open, a user can hit F1 too jump straight to the help system. Our CH window has this feature too; you can click a link inside the window to jump straight to the help topic for that object.

The super tooltips that lead to a dialog box will also show a picture of that dialog box. I'm not sure how useful that feature will be, but the User Experience guy claims research indicates "a lot of people identified dialog boxes by their look alone." I don't understand how that's possible; I suppose after repeated viewings this might be true, but after repeated viewings, wouldn't you already know what the dialog box is anyways? Curious.

Just another example that technical writing at NI involves not only writing, but also organizational decisions and hierarchy management. I'm eager to see how these super tooltips impact usability. You can see the original blog post from the Microsoft employee himself here.

Your name in lights ... sort of

A while back our marketing manager notified us of a blurb on Embedded.com relating to the awesomeness of the LabVIEW Simulation Module 2.0. I wanted to write something about it but got caught up in other activities (such as making sure products shipped on time :-)) I like this blurb in particular: "engineers can use the LabVIEW Simulation Module 2.0 to optimize dynamic system parameters for other design objectives such as stability or vibration reduction."

The reason why I like this blurb is pretty simple: I documented that feature from start to finish, including a new chapter in the user manual and two VIs with rather large connector panes. The information came across rather late in the development cycle (as information is sometimes wont to do), so I ended up adding the majority of content during NI Week in August. It was one of those features that I literally knew nothing about, so the developer was kind enough to write a giant Word document for me, which I then squeezed and squished into a comprehensive discussion of optimizing design parameters. I thought the end result came out rather well, and another developer agreed with me when he told me he had no idea what the feature was about until he read my user manual chapter.

Another major feature was the addition of "programmatic" linearization and trimming (programmatic referring to the fact that you drop VIs on the block diagram to accomplish this task instead of using only dialog boxes). Thus the blurb: "Engineers now can linearize complex, nonlinear systems modeled in control block-diagram form and use the intuitive LabVIEW graphical development environment for the entire development process for both simple and complex systems." This feature occupied my life for a period of several months, as I added new content to the user manual and documented the ever-changing VIs. The result is pretty useful and walks users through exactly how to use the Trim & Linearize VIs to linearize and/or trim a system model.

Another reason I like this blurb is because I not only wrote the help for these features, but also served as some QA during development. If a procedure was unintuitive or complicated, I tried my best to ask why it was that way in hopes of fixing it. I also was responsible for making sure the VI parameters were capitalized properly, that the icons were descriptive (we have an in-house graphic designer to help with that task), that dialog box buttons flow nicely and are informative, and so forth. The end result is something I can be proud of, and it's nice to see all the work I put in displayed like this.

On Expertise

When the TTU students visited last Thursday, one of the questions they asked was how much of an expert tech writers are expected to become on the products they document. My answer was "we're not engineers, but we're intelligent enough to deal with engineers, understand their features and products on an abstract level, and make decisions about how those features/products affect the user." I found this comment applicable to a particular situation I'm facing, which is explaining to users the rationale and functionality of the Kalman filter.

Not being an engineer, I've heard very little about Kalman filters. I hear they were instrumental in the US space missions in the 60s, especially the lunar landing. There is a section in the Control Design User Manual where we talk about the CD Kalman Gain VI, the one that you use to calculate the gain L to apply to a Kalman filter for a particular model/noise covariance. I wanted to expand this section because I feel it's particularly nebulous as to the purpose/functionality of a Kalman filter and because users can benefit from knowing why they are using this VI.

I started with some example programs we shipped in CD 2.0. Looking simply at the VI's inputs and outputs, as well as the current documentation (written by my manager), helped me understand what was going on. These resources were both extremely helpful. By seeing what inputs are required to the VI and comparing those to notes from my developer(s), I could craft some sort of explanation as to what was going on.

Unfortunately, I was wrong in several key areas. When I sent the new documentation to review, I received it back covered in enough red pen to make my 10th-grade english teacher proud. Mainly it was technical stuff the developer wanted to add to avoid confusion; but I made several assumptions that turned out to simply not be true.

We met, and he explained to me what was going on, where I went wrong, and what he'd like to tell the user. He drew several diagrams, complete with equations, that I kept. I countered with what I felt was appropriate for the user manual section. Pretty soon that "ah-ha!" lightbulb moment happened in my brain, and we agreed on some common ground for the user manual.

So now I have a new understanding of the Kalman filter, albeit on a fairly high level. The point here is that I am not an expert on the Kalman filter, control theory, or software engineering. But I am intelligent enough to work with the developers to reach a common high-level understanding of what's going on, propose how I will explain this to users, and move on from there. When I hand a document to the engineers, it is with the request to "make sure what I'm saying is correct as it pertains to this product and the functionality we offer."

To be fair, I've known all this since day one, at least implicitly. But for the past few months I've been finalizing documentation sets and not necessarily researching/documenting new features, so I haven't been in the practice of the formal review cycle. I take each review cycle as an education in the theory behind my product because I learn so much each time. It helps to have developers who are very good about working with me towards a point from which we can both communicate to the user.

More Members!

I'm happy to announce that several other technical writers/managers in the LabVIEW group will be posting to this blog. The blogging revolution at NI continues :-)

LabVIEW 8 Help Online

Those of you who are curious (or in need of assistance) can now view the entire LabVIEW 8.0 help file online. Before we were just posting PDFs and CHMs. The problem is that Google and ni.com's search engine can't access the internal text of these file types. All you could search was the abstract. But now that each help topic is a single HTML page, search engines can index that content so it's easy to find.

The toolkits and modules should have their help online too, I'm just not sure when.

Last Wednesday (October 26th), another tech writer and I woke up extremely early and drove down to UT San Antonio. We presented information about NI and technical writing to three technical communications classes. UTSA's tech comm concentration is a part of the Communications department, as opposed to some other universities where the tech/professional writing program is a part of the English department. That's part of the challenge with recruiting from universities; the tech comm / English departments are in various states of completion and organization (not to mention funding).

The trip was a lot of fun. The other writer, Lori, and I covered roughly the same topics in each class, although we tailored the approach to the subject of the class. For example, in the Writing for New Media class, I spoke about the move towards HTML-based documentation vs. the tradition of PDF-based documentation. In the design & layout class, Lori contrasted the layout of the cRIO hardware documentation with the layout of the fold-out posters for applications like Measurement Studio. I talked mainly about the atmosphere and culture of NI, for which we've won awards (come to think of it, I didn't mention the FORTUNE 100 awards. I will next time.) I also got to explain the Control Design & Simulation products I document. That was a first for me, as I have spoken only to friends and family about the products, never to a larger group. I hope my descriptions were accurate ;-)

Basically, we tried to give an impression of what technical writing life is like at NI - working with engineers, researching upcoming products, organizing the documentation, performing usability testing, things like that. We emphasized that the job is not just sitting in front of a computer and entering edits. Of course, that's part of it, but in the long run just a small part.

Although the trip fell under the umbrella of recruiting, the goal of the trip wasn't necessarily to recruit students. We mainly wanted to see how interested the students/faculty are in having us come down every so often. Judging from the response we got, I think we were successful and should continue to visit their campus in the future. In each class, students asked us questions after we'd finished speaking, which showed us that the students were at least curious about tech writing as a career. We left some surveys with the professor so the students could tell us their opinion directly.

The whole trip was fun. I like that technical writers initiate and manage the interview/recruiting process, as opposed to leaving everything up to HR. I definitely look forward to doing more recruiting events. Next week, the STC chapter from Texas Tech is visiting NI. I'm involved with showing them around (and taking them to dinner, of course!) so I'll post about that after they visit. We have a bunch of tech writers from TTU; in fact, I think I'm the only one in the group who didn't go there. Oh well, they'll just have to forgive me for going to another Tech :-)

Well it's been a little while, but I've been busy! Since we announced LabVIEW 8, the add-on modules have been running through their own crunch mode as they finish the new versions. I helped out with some of the Datalogging & Supervisory Control (DSC) module documentation. I took 3 help files through the requisite signoff processes and edited a Dev Zone document about the new Domain Account Manager in DSC 8. Also last week I attended three days of training on control design, system identification, and simulation theory. As you probably already know, NI has LabVIEW add-ons that address each of these areas. The course was for people who hadn't had a control design course in awhile. Seeing how the math comes together with theory really helped me understand more about my products. I suppose it was the equivalent of a semester or two in college, although if you count the differential equation math involved, it might have been longer.

The push for two of my products is ramping up as the Simulation Interface Toolkit 3.0 was announced to the world a couple days ago. I've been involved with numerous last-minute documentation updates and changes. Some of the stuff is okay to defer until the next release of the toolkit, but I am somewhat of a perfectionist and like to get things as right as possible the first time. It's difficult trying to consolidate so many different edits from so many different people in such a short amount of time. And as I'm receiving these edits, I'm thinking about how I don't want to be the one holding up the software release. Hopefully there will be only minimal differences between the documentation and the software itself ;-)

Tomorrow and Friday is NI-TC, which is an internal conference for the entire Tech Comm department (at least, those of us in Austin). The three Tech Comm departments include technical writing, documentation production, and localization. Doc Pro are the folks who help us writers out with art, page layouts, formatting, templates, and the like. They also send printed documents to the printer. I don't have any printed documentation in any of my toolkits (it's all either a PDF on a CD or a bunch of CHMs), so I don't interact much with the printer team. Of course I lean on the Doc Pro team heavily, especially with all the equations and engineering block diagrams in my documentation. Localization takes care of translating our documents into the five languages we support. Again, none of my documents are localized, so I don't deal much with localization, or L10N (so named because of the ten letters in between L and N).

Anyway, don't get the idea that we sit around discussing grammar and punctuation preferences - we save that for the style guide committee meetings :-) The conference consists mainly of the tech comm members presenting to each other about technologies we use, trends we've spotted, products we're working on, features we like, and processes we find either useful or hindering. There are also some tangentially-related discussions, like a showcase on how we recruit for the department and tips for ergonomic working. It's also a good chance for us all to get together in the same room and chat for two days. At the end of the conference is a demo fair, where we physically demonstrate products and/or technologies. For example, we have two writers showcasing some upcoming products that none of us have really seen. We can pick each others' brains about functionality, usability, and of course the coolness of everything we see :-)

And speaking about recruiting, next week I'll be heading down to UT San Antonio with another writer and a manager. We'll be presenting to several classes and talking about what NI does, what tech writers deal with on a daily basis, and things like that. I'm looking forward to it, because I've been wanting to get more involved in the recruiting machine. I hope to get a chance to plug that fact that NI was chosen to test the controllers for the Xbox 360! That's a way better example of test & measurement than talking about cell phones and motorcycles, although motorcycles are still pretty cool. And of course the Shiner brewery runs on NI software, too.

Two more links for the day ...

- Today NI officially announced LabVIEW 8. This is the framework for most of the upcoming add-ons, so we've all been working with version 8 for awhile now. As far as I'm concerned, however, the most important part of the announcement was the free breakfast tacos we all got this morning :-) Mmm, bacon and egg.

- The newest issue of Wired has a great profile on tech-writing superstar (hah!) Tim O'Reilly. The article talks more about his personal philosophies and his industry prescience than it does about technical writing, but some relevant talk still makes it in there. What, is tech writing boring or something? Heaven forbid! :-)

Anyway, O'Reilly books are probably the benchmark for all third-party manuals out there. I've read/used several, and I know other R&D employees here have copies of one book or another. The article is a fun read on how his business got started.

Formatting nuttiness! The next version of MS Office will include support for Adobe's PDF format. Brian doesn't mention what "native support" really means, but I imagine there will at least be an "Export to PDF" button or a similar option in the Save As dialog box.

There are a bunch of things to talk about with this move. Is this a shot across the bow at Framemaker? No, probably not; everyone knows that MS Word can't handle the organization and printing of huge documents the way Framemaker can. But this announcement is definitely aimed at Acrobat. Is this a shot at OpenOffice.org? Most definitely - exporting to PDF is listed as a primary feature of OpenOffice.org Writer. The capability is certainly one of the reasons I use OpenOffice.org at home. Now OOo has one less differentiating feature. But hey, it's free, and the good ol' city of Austin uses it too!

PDF support also puts MS software back in the running for the state government of Massachusetts, which mandated that all government employees must now use open-format office software. MS Word's .doc format doesn't qualify under that rule, but the PDF format sure does.

What remains to be seen is how PDF support will affect Metro, MS's own easily-accessible-open-everywhere format. What advantages will Metro have over PDF? Instead of simply equalling PDF's functionality, Metro now has to differentiate itself. Could be tricky; could be interesting. Certainly the inclusion of fun transparent "Aero" graphics can't be enough, nor can the "rights-management" functionality MS plans to include.

I doubt things will change much here at NI, where we use Framemaker for the PDF documents. I think this move is solely to placate governments (both local, state, national, and international) that do not want to rely on a single software vendor for access to creating and reading the majority of official documents. Massachusetts was just the latest example; more are sure to follow.

Perusing /. as I normally do netted me this article about how 'IT' jargon disrupts the workplace. The LabVIEW style guide we follow has a strict 'no jargon' policy. For example, we are expected to define acronyms on their first usage in a help topic or PDF manual chapter. For the Control Design & Sim documentation, I define terms like single-input single-output (SISO), multiple-input multiple-output (MIMO), linear time-invariant (LTI), and other acronyms fairly regularly. It gets a bit tedious, but the thought and concept behind the guideline is sound. We can't all be control systems designers :-)

Stepping outside of your own mind is hard to do. After writing and editing Control Design documentation for so long, I wouldn't consider LTI to be an acronym worth defining every topic. But the next person who reads the manual might be a complete newcomer, or they might come from an industry where LTI means something else entirely. So it's just become a reflex I try to engage while editing a document: did I already define that acronym in this topic/chapter?

Our style guide lists acronyms we don't have to define. These include CPU, RAM, DLL, TCP/IP, etc. These also include acronyms related to NI products like PXI, DAQ, and GPIB. For what it's worth, I think DAQ is a great acronym.

Of course, it's not just acronyms: terms like "rate-monotonic scheduling" and "positive semi-definite" occur quite frequently in the CD & Sim documentation. What's the Boltzmann constant? In these instances, it's up to a developer to tell me if the term is industry standard or not. Can we expect customers purchasing this product to be familiar with these terms? I certainly didn't know what they meant when I first heard them. Unless I hear otherwise, I'm expected to define them, which I think is a good policy. You never know who will be reading your documentation.

Change is a big reason that IT jargon confuses people so much, at least in the realm of computer hardware. If you know what a Pentium 4 is, do you know what a Pentium D is? An Athlon X2? These are more recent versions of older CPUs. These technologies change so much that as soon as you learn the difference between ISA, PCI, and AGP, you've got to throw PCI-Express x1, x4, and x16 into the mix. Not to mention IDE vs. ATAPI vs. PATA vs. SATA. The same goes for software, where people use Javascript for a couple years and then switch to another language; pure HTML is being phased out in favor of a mixture of xHTML, PHP, and CSS; not to mention XML and other formatting/programming languages. This industry is in a constant state of flux, a fact that relates nicely to the multi-tasking issue I talked about a couple months ago.

Also, I discovered that my blog is #4 on Google's Blog Search for "LabVIEW." Joel Sumner occupies the top two spots. I guess this means people are reading our blogs! :-) I'm going to try and read and link to more technical writing blogs to get this address out to more people.

In her last comment, Kaylene asked me if I ever get discouraged about the whole "no one reads documentation anyway!" issue. I typed out this long response, then decided it needed its own separate entry.

===

The joke around here is that no one reads the manuals unless they're bored while on hold with phone support :-) I don't really get discouraged about this issue because the products I write about are interesting enough to motivate me personally, and because whether or not anyone reads what I write, I know it's there in case a customer needs it.

In the case of some more complicated features I'm currently writing, I've had developers come up to me and say "I didn't understand what this feature was about or how it worked, but I read your user manual chapter, and now I get it." So there's some small comfort for me in that aspect :-)

Funny story, tying the iPod and tech writing together: this past weekend I bought a slightly-used iPod mini from a guy on craigslist. He advertised it as being in the original packaging, and lo and behold, the user manual was completely sealed in its original plastic. I joked with him, "it's guys like you us tech writers hate!" But I know it's just because the thing is so easy to use that detailed documentation is unnecessary. The menu items and such on the iPod are so self-explanatory that Apple could probably get away without shipping an iPod manual; but that looks unprofessional from a marketing/brand standpoint, so I doubt that'll ever happen. At my last job, I spent a couple months overhauling the manual and packaging the user received with their computer. We tried hard to make a lasting impact with a "professional" presentation, even though the information inside is as simple as "Plug the blue monitor cable into the blue video port on the back of the computer."

I do read user manuals and instructions sometimes; it just depends on the product. For instance, I had to read my coffee maker's user manual to find out how to brew at a specific time in the morning. Does that suggest an unintuitive user interface? Probably; I never would have figured the steps out on my own by just looking at the buttons on the front. So the issue might be, is the user aware that they don't know everything about the product? Is their personality type the kind to admit they aren't smart enough to figure out which functions do what and which buttons go where? I suppose these more "modest" types of people might be more inclined to leaf through the user manual (or page through the online help).

I recently bought Jade Empire for the Xbox and looked through the user manual while waiting through the incredibly long loading screens. The combat system in the game is confusing at first, and though the manual didn't provide all the information I need (I'm a "big picture" person, a viewpoint which seems to be rarely presented in the documentation I come across), it helped me understand what I was seeing onscreen so that I could figure the system out after a little while.

However, for something like a computer part (optical drive, video card, etc) I definitely don't read the manual. That's only because I've been installing computer parts for several years and don't need a manual to tell me what I already know :-) And I have not broken the seal on the iPod's documentation; I doubt I ever will :-)

It's interesting documenting a programming language though, because our end users are using our products to make other products. So we're really the middleman. A large part of our documentation comes in the form of function reference: we detail the purpose of each function as well as the relevant arguments and data types. Coming from a CS background, I know this information is extremely helpful, especially because the majority of the programming done out there is not original design, but simply maintaining and updating existing software. In these situations, function reference is invaluable, and I would hope that no one would call tech support just to figure out how a particular parameter affects the function. Then again, you never know :-)

Another reason I don't get discouraged is because I know there are some people out there who do read the documentation. I know this because we get comments on the documentation when people get stuck trying to work something out. Of course the comments are usually about incorrect or unclear information, but that's just because the motivation to say "Good documentation, guys!" is not as strong as the motivation so say "Hey, this documentation sucks!"

However, I don't expect someone to sit down and read the user manual cover to cover. Especially not an online user manual. This expectation factors hugely into the way I organize and design the help system for the Control & Sim products. For example, we rely a lot upon the "Search" and "Index" features of HTMLHelp. If we don't organize and test these systems properly, we're reducing the usability of the help system. We do a lot of internal testing, and we sometimes test actual users, but we can always do more in that respect. The fact that we're expected to participate and drive this organization and testing is just one reason I enjoy working here :-)

Today I am trying to track down a naming issue. Microsoft doesn't brand Visual C++ with version numbers anymore; they stopped doing that after VC++ 6.0 (which I used as a CS student for the semester and-a-half I was one). They switched to the .NET 200x nomenclature. So in updating documentation from that ancient period of VC++ version numbers, I'm trying to obtain a one-to-one mapping of "7.x" versions to ".NET 200x" versions. I've been bugging a couple developers here, including Brian, but if anyone out there has a solid answer for me, drop me a comment down below and we'll talk.

I'm pretty excited about several of my documents shipping, because I've been working on them since late January. Of course, I'm experiencing so-called "feature creep" as developers work in last-minute changes to the code. Some of these changes affect the documention I've already had reviewed, so I have to get some portions reviewed again. In the case of completely new features, I just make sure that the developer and my lead writer see the new/changed content once.

NI matches charity donations up to $1000 per person per year. Obviously, everyone is busy collecting money for Katrina relief efforts. I've done my own fundraising drive and will end up with something close to the limit that I'll pass on to the Red Cross.

I realize this entry is rather boring; hopefully I'll have some fun stuff to talk about once I have more free time to post, e.g., after my documentation ships :-)

In the meantime, I'll post links to this 1/2 TB hard drive. Half a terabyte?! The hard drive in my first computer was 540 megabytes. I feel lucky to have witnessed those days :-) Of course, my dad was there when computers had no hard drives at all. Scary thought! I wonder who the first person was to say "Hey, maybe people want to store more than a few kilobytes of information after they turn off the computer." Non-volatile storage - what a genius :-) Anyway, with 4 IDE ports and numerous SATA ports per motherboard, storage is becoming virtually (hah) limitless. But I'm sure people said that back in the good ol' days of the 5.25" floppy ...

I'll post one more link to one of Apple's newest gizmos. I've been putting off buying an iPod for so long now, but I think I might have finally caved in with this latest announcement ...

Last week was NIWeek 2005. It was my first time attending, and I had a blast :-) I love seeing all the new things NI is doing. The product demonstrations at the keynotes were especially interesting. My favorites were the table saw demo and the ball bearings demo. You can see them both by watching the keynote speeches. Also, because I'm an audio nerd, Alain's presentation on CompactRIO audio algorithms was fun to watch (and listen to). And then of course there's the Virginia Tech presentation on their DARPA vehicle. There was just so much to see and do.
I also want to comment on an article I found on Slashdot a couple days ago. As an Interdisciplinary Studies (IDST) graduate myself (from Virginia Tech, no less), I'm really happy to see the field getting some attention in the press.

One of the more pertinent quotes from the article is "If you have only technical knowledge, you are vulnerable." Because I haven't been in the "real world" for too long (oh, two years is plenty!) I can't say for sure how true this quote is. I do know it's true in my line of work, and I've heard many other people, such as engineers and evelopers, talk about the need to attack problems from many different angles. All I know is, IDST certainly helped me get this job and continues to help me do my job well. IDST focuses on creative thinking, information analysis, and problem solving, both of which can be more crucial to a job than straightforward technical knowledge. For example, as a technical writer, I'm not expected to know much of anything about control design or simulation. I am, however, expected to be able to learn enough about these fields to write well about the products. This expectation involves plenty of facets of the IDST major, from synthesizing information to making cross-disciplinary connections. Perhaps my main challenge at work, or at least the most common challenge, is translating what the engineers/developers tell me into plain English. The IDST major certainly helps with that aspect of my job.

To that end, I would have liked to see some commentary on the combination of computer science/IT and english, which is pretty much the way I went. Those are more disparate disciplines than IT/CS & business. But, like I said, I'm happy to see IDST getting some press.

Ah, it's been a little while, but things have been busy around here. NI Week 2005 is coming up, which is pretty exciting. I haven't been to one yet, because I only got here last October. But I'm assured it's a good time. I'm excited to see what our customers are doing with the Control & Simulation products. Hopefully I'll get a chance to get some feedback on the documentation and what I can do for the next release to make it better or more effective.

NI Week 2005 has an entire summit devoted to Embedded Engineering & Control Design, which comprises the groups for which I write. That's taking place on Tuesday and Wednesday. I'm helping the developers staff three product demo booths, which show off the ways our products interact with one another and produce useable results. I'm a little nervous about talking directly to customers, since I haven't done that since my last job. But again, I'm looking at it as an opportunity to get to know our user-base better and perhaps help them out. I've seen a couple customer emails that reference the documentation on which I'm working, but since none of my major work has shipped out with a product yet, this will be the first time I can possibly incorporate suggestions into the writing itself. I want to spend as much time there as possible. We have presentations by Ford, Whirlpool, Quanser, and many other industry/academic notables. I think Quanser's presentation on haptics in LabVIEW will be really interesting.

This weekend I'll be in Dallas (technically, Irving and Grapevine) for the 10th annual QuakeCon. I mention this because Hall Martin posted recently about video game technology and I hope to see some new stuff there, like the DOOM Movie and Quake IV. Hall remarks that without games, the drive/demand for PCs wouldn't be as high as it is today, and I agree. Who needs an Athlon X2 to run Word? Gaming opened the way for technologies like virtual instrumentation to trickle down to consumers.

Although I hope to see some new stuff at QuakeCon, I realize that events like E3, GDC, and AGC are more business-oriented and would perhaps focus more on the technology. But I know QuakeCon will be as informative as it is fun. I'm really excited to hear John Carmack's keynote, even though I probably won't understand a word he's saying.

So with QuakeCon, NI Week, and an internal conference I'm helping to organize coming up in October, I'll be running around like crazy for the next month or two. Maybe I'll even have some spare time to write documentation :-)

I love how I'm supposed to review the error codes that ship with the software. Nothing is as frustrating as confusing error codes. The LV doc team makes a big effort to document every error code, give examples as to why the error might have occurred, and suggest possible solutions/workarounds. That sort of attention to detail can make a big difference.

Brian Tyler, who works on integrating .NET with LabVIEW, posted a hilarious story that another LV developer emailed out this morning. Check it out, it's extremely well-written :-)

One of the most striking differences, in my opinion, between Windows 3.1 and Windows 95 was the taskbar. Windows 3.1, if you recall, relied mainly on the Alt+Tab keyboard combination to switch between programs that were running at the same time. Sure, you could use the program's minimized icon on the desktop, but then you had to minimize the window and double-click on the icon. While Windows 3.1 was designed for multitasking, the UI for switching between tasks was not as obvious as the taskbar of Windows 95 made it to be.

I remember the first time I saw my dad dial up to the World Wide Web. I think it was early 1995 or late 1994. He had to dial up the ISP using one program, which I vaguely recall as having the word "Winsock" in the name. After that program connected to the WWW, he had to Alt+Tab back to the Program Manager and launch NCSA Mosaic to actually browse the web. I remember thinking at the time that switching between the two programs in that fashion seemed unintuitive. The notion seems quaint now, with the advent of the taskbar and its glorious reminder that we can run as many programs at once as our computer's RAM can handle.

I mention all this multitasking nonsense because of an article I caught on CNET today. I've seen a bunch of these articles appear over the past couple years that describe frazzled executives and workers who can't cope with "information overload." This CNET article sounds the typical alarm about people who need to "unplug." But I think that if they talked to a younger generation of workers, perhaps those who are just entering the workforce after college, they would find that multitasking is just a fact of life, and perhaps a source of pride.

Although I am old enough to remember the pre-Internet days of communicating, I pretty much grew up using IM, email, and all the multitaskable tools of which the article speaks. I was one of the first people I knew to get broadband access in late 1998 (my mom was tired of picking up the phone and hearing those wonderful modem-screeching noises). Playing lots of video games enabled me to pay attention to many things at once. And, although I lament the fact now, watching MTV and other rapid-fire television programming left my attention span able to cope with short barrages of intense information.

This familiarity with multitasking led to my acceptance of the idea as normal. I guess I can't imagine not multitasking or not being available by cell phone/IM/etc. The workplace has changed so much over the past 15 years, but because I only entered the workforce two years ago, I slid easily into a job that required me to wear many different hats at all hours of the day. Even here at NI, being a technical writer definitely tests my ability to multitask, but I find myself almost looking forward to the challenge.

Another pertinent effect of being familiar with multitasking is that I learned very early on how to take time out for myself to unwind or unplug. That's why I can't really relate to the CNET article. Those interviewed stressed the problems they've had adjusting. But I spent my entire pre-work life "adjusting," although I didn't know it at the time. So that's why I'm comfortable with the thought of multitasking 8 or 9 hours a day: I know how to do it and I also know when to take a break and chill for a bit. I imagine it would be hard to adjust to such a multitasking-oriented workplace if you were not already used to being reached by IM, email, cell phone, etc. anywhere you went.

Maybe as more people raised similarly enter the workforce and become managers and executives, we'll see articles and studies like these disappear because we'll all have become used to these things called computers and how they keep us in touch with various facets of work at the same time. Of course, technology moves at a rapid clip, and it's all we can do just to keep up - so it's possible that what I now consider multitasking will seem as quaint as the notions I espouse in the first two paragraphs. I'm sure the next generation will have its own set of workplace issues to get acquainted with.

On a completely unrelated note, I find it amusing when software developers identify themselves with the software. Example: "The code I wrote pops up an error when a user tries to do that" becomes "I pop up an error when the user tries to do that." I know it's shorthand (or shortmouth in this case), but I always like to imagine one of our developers knocking on a customer's door and holding up a sign that reads "ERROR!" in big red letters. Of course, now when someone asks me about a help file I've written, I say "I have a paragraph about that" or "I talk about that here." The notion of "owning" help files is in itself something I've thought about recently. Maybe I'll make that the subject of my next post :-)

On an even more completely unrelated note, this is pretty sweet.

Want to see how we write? You can now search our HTML and PDF help online. Currently only core LabVIEW deliverables are up; these don't include any add-ons (like my Control Design & Simulation stuff). I'm not sure if or when those docs will go up, but I don't see why we wouldn't post them. Also, since the linked web page says " NI Products" and not "LabVIEW," I assume that other product manuals will end up here as well.

If you notice any issues, be sure to report them. You can contact the web team or leave a comment here and I'll get the message to the appropriate people.

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

Two of my products are in beta right now. Both programs are generating feedback to the developers, which is very good of course. But the interesting thing I'm dealing with today is trying to fit new features/tweaks/bug fix documentation items into the existing structure of the documentation set. What I mean is, I've spent the past several months working with the developers and my manager to organize the documentation set in a specific way. (That effort brought its own challenges, which are kind of fun because they represent a larger LabVIEW effort to make the documentation easier to use, but I'll talk more about that in a later post.)

Anyway, now that beta customers' feedback is trickling in, the developers implement certain suggestions and then let me know I need to incorporate the new behavior into the existing documentation. Today I'm challenged to find places for these seemingly random tidbits of information that do not have a defined place in the existing structure. Sometimes I look at a what a developer says and think "Oh, I know exactly where that should go to make the most sense." Today though I've run into at least one beta-generated behavior change that doesn't fit anywhere. I'm reluctant to make a new topic for two reasons: 1) doing so calls the organization of the help file into question, and 2) an entire topic implies that this behavior is extremely important for the user to know, which might not be the case. Besides, a separate topic with one paragraph in it doesn't make much sense. I considered just adding a line to the "Known Issues" section of the readme file, but that implies there is a bug or something, which is not the case.

So part of the problem is that I don't know how much prominence to give to a certain change. Will users run into this situation often enough that this behavior merits its own heading? How will adding that heading affect the layout of the help file? Is this information related to the other information in this help topic? Questions like that. I'm glad that I have the freedom to even ask these questions and figure out answers in my own way. Sometimes, though, I wish I could just have a "Miscellaneous Information" help file with random tidbits of information about certain behaviors. The main LabVIEW Help has set a similar precedent with its "Caveats and Recommendations when doing X" topics, which is along the lines of what I'd like to do, but this particular behavior isn't a caveat or recommendation.

I'll figure out a home for this orphan piece of documentation, though. And in the future, I will look for ways to design more "flexible" documentation that can accommodate these tidbits better. I'm learning a lot from my first betas.

And speaking of random tidbits of documentation, Blogger apparently adds <p></p> tags to each paragraph, even if you don't specify them when editing raw HTML. Is that behavior documented anywhere?

Today I emailed a link to this blog to the LabVIEW team, as well as the Tech Comm team (which includes all technical writers, artists, and others who assist in document creation). It's funny to think that within a single company, not everyone knows what everyone else is doing. Then again, my last job was at a company with 25 people; NI has several thousand employees worldwide. I'm still getting used to the size increase.

On a spur-of-the-moment impulse, I went looking for other technical writer blogs (Google for "technical writer" +blog). I found a couple that look interesting. It seems that most of these guys are freelance and not attached to a company, like me. Regardless, I'll list them here:

• Document Hack - This looks like a good resource. I'm going to peruse this site and get more ideas about topics I can write about. Plus, "Document Hack" is a cool title. Much better than mine, I think :-)
  
• Writers India - This could be good for getting a global perspective on user documentation and technical writing.
  
• Rob Caron's blog - This guy is at Microsoft and works documentation for the Visual Studio team.

And here is a fun article from the NYC chapter of the STC about the presence and usefulness of tech writing blogs.

It's nice to see there is precedent for a technical writer to be blabbing about his or her job function on the Internet.

Welcome to Technically Speaking!

My name is Ryan. I'm a technical writer for the LabVIEW Control Design & Simulation group at National Instruments. When people ask what I do for a living, I respond with "I write software manuals." I follow that up with an explanation and then maybe a little bit about what the LabVIEW Control Design & Simulation products do. Somehow I don't think there is a common definition of "technical writer" the way there is for "district sales manager" or similar positions. Along these lines, I intend for this blog to explore various aspects of technical writing that I deal with on a daily basis. Because my work is about combining technology and writing, you can expect that synthesis to spill over into this blog. I promise to stay somewhat on topic and to try hard not to misspell any words.

A little bit about me:

I joined National Instruments as a technical writer in October 2004. I moved to Austin from Richmond, VA, where I lived for a year after graduating from Virginia Tech in 2003. In my spare time I do fun things like produce electronic music, spin techno records, read lots of books, and enjoy the sunny weather in Austin.

I encourage you to check out our other other blogs if you want to pick the brains of more NI employees.

Stay tuned!