One reason I enjoy being a technical writer at NI is that we don't just write stuff and draw squiggly editing marks on other people's papers. True, that is some of it. But beyond the writing and editing, we are allowed (and encouraged!) to suggest and implement improvements to the software.
For example, all LabVIEW's VI/function help topics contain buttons labeled Place on the block diagram and Find on the Functions palette. Clicking these buttons opens an interactive pathway between the help file and LabVIEW itself. The idea for buttons like these originated with the LabVIEW technical writers. They saw a need, proposed a solution, follwed through, and the rest is history.
I recently proposed, and am in the middle of implementing, two help system improvements of my own. They both deal with LabVIEW MathScript and the way users interact with help in that environment. I was pretty nervous when it came time to present these proposals to the appropriate people because I'd never done this before. We all sat down in a brainstorming meeting to discuss the merits of my proposal. I started off basically by saying "Tell me what I did wrong." I was worried that I'd proposed some fatal flaw that would get my proposal rejected, or that I'd get the dreaded "That's great Ryan, but we don't have enough time to do this." But none of that happened.
That meeting was an eye-opening experience for sure. Now that I have that under my belt, I am moving forward with getting my idea actually implemented in software. It's pretty neat to see a checkbox there just because I asked for it (and several people approved it, of course). Oh, that sounds so geeky. But it's true.
I'm talking only about the two ideas I proposed, but I've watched several other LabVIEW technical writers, who are newer here than I am, have come up with other awesome ideas for the help system. These features improve the user's ability to submit feedback on our help files, scan and navigate a long help topic, and find what they're looking for in the index. I really think these features will add value to LabVIEW.
An interesting side effect of this process is that we get mini-tutorials in project management. We propose the feature, figure out how to (and who will) implement it, delegate tasks, manage resources and deadlines, and see everything through to completion. This is the norm for a developer or project manager, for but a technical writer? It's pretty cool. At least it is to me :-)
Sure, we might not impact a customer's life as much as if the developers decide to add a new ODE solver or signal window to the palette. But I can point to a particular feature and say "I thought of that and made it happen in reality."
March 15, 2006
March 6, 2006
A lot of software developers I know (both here and elsewhere) have expressed interest in designing/coding video games. In fact, that's originally why I entered college as a Comp Sci major. As a parallel, I wonder if any technical writers secretly dream of writing strategy guides.
February 21, 2006
How do I turn this thing on?
I caught the following passages over at HardOCP this morning. The quote comes from a review of the Voodoo ARIA Home Theater PC (HTPC). Although the product is a Windows-based computer, the outer case and presentation to the user is drastically different from a typical PC.
The emphasis is mine. I wonder: how many users end up not finding what they want in the LabVIEW documentation and then reduce their opinion of our product? Is there anything we can do about this?
Coincidentally there is an ongoing thread on the Dev Zone about how users best learn LabVIEW. It's interesting to see some of the comments there regarding the documentation. Because we (tech writers) don't deal with customers on a daily basis, it can be a little unnerving to hear their unbiased opinions about our work! But all feedback is helpful and (given the proper resources and time) will lead to improvements. This thread is an opportunity to get some interesting data points and scenarios from actual customers, which is great. We're also working on ways to give customers a more direct way to comment on the documentation.
One thing that I mentioned earlier was the extreme lack of documentation on the Voodoo PC ARIA. Granted, it’s a new product for Voodoo, but we spent a small fortune on this system and I was actually scared when I first pulled it out and realized I had no idea how I was going to use this system in conjunction with my entertainment center. My perception of value had dropped significantly. Heck, my $250 Panasonic DVD player has a 100% complete manual that explains every single nuance of every single function you could possibly use.
I didn’t even have the first bit of information regarding how to use Windows Media Center Edition – so I did what any guy would do – I hooked it up and started pressing buttons.
It took me a good hour to figure out how to get a properly sized video signal to my TV, so I figured that it would be a perfect question for Voodoo to answer.
... My point of contact for anything I needed was with my sales representative, Lance. Lance and I exchanged a couple dozen emails and phone calls, many instigated by him and inquiring to how my system was doing. That calmed many of my fears about being stranded.
Lance got me in touch with their technical support department and I was quickly assisted by their knowledgeable staff in setting up the ARIA to not only interface properly with my HDTV, but to be sure that my Audigy 2 ZS was properly configured.
I also received updated documents on the ARIA’s functionality that I hope will be included in future ARIA sales – they were certainly things I would have liked to know out of the box.
The emphasis is mine. I wonder: how many users end up not finding what they want in the LabVIEW documentation and then reduce their opinion of our product? Is there anything we can do about this?
Coincidentally there is an ongoing thread on the Dev Zone about how users best learn LabVIEW. It's interesting to see some of the comments there regarding the documentation. Because we (tech writers) don't deal with customers on a daily basis, it can be a little unnerving to hear their unbiased opinions about our work! But all feedback is helpful and (given the proper resources and time) will lead to improvements. This thread is an opportunity to get some interesting data points and scenarios from actual customers, which is great. We're also working on ways to give customers a more direct way to comment on the documentation.
February 3, 2006
How Do You Do That Again?
We consistently get feedback from our customers that the example VIs we ship with LabVIEW are really helpful. The developers put a lot of time and effort into creating examples that demonstrate new features and show how to accomplish certain tasks using LabVIEW. In addition, the examples serve as great templates for certain common applications. For example, if you want to acquire a measurement from a DAQ device, perform some measurements and signal processing on the measurement, and display the results in a plot while simultaneously writing data to a file for later use, we ship example VIs that do just that (I think; don't quote me on that :-). So you don't have to go through the trouble of digging through our help files to figure out how to daisy-chain these VIs together. We've done the majority of the work for you.
The Control Design Toolkit is a great example of how to create, well, examples :-) We categorize all the examples into separate .llb files, one for each palette. Coincidentally (or not!) each user manual chapter corresponds to a palette. So for the upcoming release, when I was trying to find a way to highlight the examples, I simply added a canned statement to the beginning of each chapter that refers the user to a particular .llb. Because we structured the examples so well from the ground up, each example .llb maps to a chapter, and I made the connection pretty easily.
The examples serve as a great connection between the tech writer and the developers. The developers create the examples and document them by adding block diagram/front panel comments and a VI description that shows up in the Example Finder. So in this sense, the developer "owns" the example. But as a tech writer, my responsibility is to make sure the descriptions are accurate and helpful. So yesterday I just finished scrubbing all the descriptions for each example. It was a good long effort, but it pays off when customers tell us how easy it is to use the product, because all they do is open a example and go to work.
Another product I work on recently received some feedback that the examples could be even more useful if they were not so complicated. This is another issue that crops up also in documentation - how complex is too complex? In this case, a professor was teaching his students the fundamental concepts that our product demonstrates, and the shipping examples were too high-level to be of much use because there are so many functions contained in each. He suggested simpler examples, with just an input, the function, and some output. This way his students could see the operation of a particular function without the "noise" of having so many other functions and wires around.
We talked about this feedback for awhile and decided it was worth it, for the upcoming product, to develop these "basic" shipping examples to demonstrate the purpose/functionality of almost every function we ship. It'll take a bit of time to do well, but the result will be a less-intimidating product that will be of more use to everyone.
So now we have a split between 1) providing pre-written programs and 2) demonstrating how to use the product to do what you want. These requirements are not mutually exclusive, but it can be hard to design a good example for both requirements. Oftentimes, as in the case of the aforementioned product, the examples are wonderful at The Control Design examples are split into two directories: Getting Started (which has the .llb files organized by palette) and Case Studies. We want users to look in the Getting Started directory to become familiar with the concepts of the product: how to analyze a Bode plot, how to discretize a PID controller, and so on. The Case Studies are not necessarily prebuilt applications, but they take a more in-depth look at the toolkit by, say, designing a controller for a hard drive's read/write head within certain constraints.
LabVIEW includes a tool called the NI Example Finder, which you can access by launching LabVIEW and selecting Help»Find Examples from the pull-down menu. If you get stuck, try playing around with this window and seeing what you find. I bet you'll find some useful applications just sitting there, waiting to be developed. Each module and toolkit, as well as some hardware, also ships some examples with their software. Check them out and see what you come up with.
I'm taking more opportunities to suggest examples and make sure they are well-documented. In addition to example VIs, we're always looking for ways shrink the "installation-to-usage" time that measures how quickly a user can *use* the product after installing it. We've been coming up with some great ideas, some of which I hope to implement in the coming months.
The Control Design Toolkit is a great example of how to create, well, examples :-) We categorize all the examples into separate .llb files, one for each palette. Coincidentally (or not!) each user manual chapter corresponds to a palette. So for the upcoming release, when I was trying to find a way to highlight the examples, I simply added a canned statement to the beginning of each chapter that refers the user to a particular .llb. Because we structured the examples so well from the ground up, each example .llb maps to a chapter, and I made the connection pretty easily.
The examples serve as a great connection between the tech writer and the developers. The developers create the examples and document them by adding block diagram/front panel comments and a VI description that shows up in the Example Finder. So in this sense, the developer "owns" the example. But as a tech writer, my responsibility is to make sure the descriptions are accurate and helpful. So yesterday I just finished scrubbing all the descriptions for each example. It was a good long effort, but it pays off when customers tell us how easy it is to use the product, because all they do is open a example and go to work.
Another product I work on recently received some feedback that the examples could be even more useful if they were not so complicated. This is another issue that crops up also in documentation - how complex is too complex? In this case, a professor was teaching his students the fundamental concepts that our product demonstrates, and the shipping examples were too high-level to be of much use because there are so many functions contained in each. He suggested simpler examples, with just an input, the function, and some output. This way his students could see the operation of a particular function without the "noise" of having so many other functions and wires around.
We talked about this feedback for awhile and decided it was worth it, for the upcoming product, to develop these "basic" shipping examples to demonstrate the purpose/functionality of almost every function we ship. It'll take a bit of time to do well, but the result will be a less-intimidating product that will be of more use to everyone.
So now we have a split between 1) providing pre-written programs and 2) demonstrating how to use the product to do what you want. These requirements are not mutually exclusive, but it can be hard to design a good example for both requirements. Oftentimes, as in the case of the aforementioned product, the examples are wonderful at The Control Design examples are split into two directories: Getting Started (which has the .llb files organized by palette) and Case Studies. We want users to look in the Getting Started directory to become familiar with the concepts of the product: how to analyze a Bode plot, how to discretize a PID controller, and so on. The Case Studies are not necessarily prebuilt applications, but they take a more in-depth look at the toolkit by, say, designing a controller for a hard drive's read/write head within certain constraints.
LabVIEW includes a tool called the NI Example Finder, which you can access by launching LabVIEW and selecting Help»Find Examples from the pull-down menu. If you get stuck, try playing around with this window and seeing what you find. I bet you'll find some useful applications just sitting there, waiting to be developed. Each module and toolkit, as well as some hardware, also ships some examples with their software. Check them out and see what you come up with.
I'm taking more opportunities to suggest examples and make sure they are well-documented. In addition to example VIs, we're always looking for ways shrink the "installation-to-usage" time that measures how quickly a user can *use* the product after installing it. We've been coming up with some great ideas, some of which I hope to implement in the coming months.
December 27, 2005
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!
December 12, 2005
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.
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.
December 8, 2005
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!
December 7, 2005
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.
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.
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.
December 5, 2005
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.
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.
November 15, 2005
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.
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.
November 11, 2005
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 :-)
November 9, 2005
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.
The toolkits and modules should have their help online too, I'm just not sure when.
November 2, 2005
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 :-)
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 :-)
October 19, 2005
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.
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.
October 3, 2005
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.
- 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.
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.
September 23, 2005
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.
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.
September 14, 2005
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 :-)
===
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 :-)
September 8, 2005
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 ...
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 ...
Subscribe to:
Posts (Atom)