Raise your hand: who's heard of Web 2.0? This is the phenomenon that spawned sites like Google, flickr, del.icio.us, Wikipedia, Myspace, and many other "killer apps" for today's Internet. Even Web stalwarts like eBay, Amazon, and Slashdot predicted Web 2.0 long before it existed by making user comments crucial to the site's operation.
There are several discussions as to what Web 2.0 actually is, but the consensus seems to be that Web 2.0 consists of sites that a) run more like applications and b) contain content that is largely defined by users.
Think about Google. How does it provide all the content that it searches? It doesn't; a globe full of Internet users provide the content. And yet Google has stock worth like $380 a share. It provides none of the content; only mechanisms for searching and organizing that content. The same goes for Wikipedia. It falls on the Wikipedia users to provide all the content for the site. Without users, the site is useless. Same with flickr and del.icio.us. Collaboration is the key.
I write about this phenomenon for a couple reasons, but I share it on this blog because Microsoft released their own wiki on MSDN last week. The wiki consists of documentation for Visual Studio and .NET products. Each page is written by Microsoft's technical writers, but because this is a wiki, users can add their own comments to each page.
I really like this idea. I imagine that LabVIEW users know way more about how LV works than the technical writers do. That' s not a slight against my co-workers; rather, it's a recognition of the fact that we are limited by company resources and time. Users, on the other hand, play with a single LabVIEW version for years, while we have to move on the next project once the current one is finished. Not to mention that users actually use LabVIEW. Sure, there are one or two tech writers who can handle G programming, and we all take the LabVIEW Basics courses that NI offers. We use several VIs to help us with our numerous documentation processes. But our focus is on writing, not programming. I'm pretty sure that none of us have developed a test & measurement application.
Imagine if you opened up a user manual and noticed an error in the documentation. Or you notice that, based on your own experience with the product, a key piece of information is missing. If you're dilligent, you send feedback to NI, and a year or so later, you see the corrected material in the new version of the user manual.
Now rewind and imagine opening up that user manual and noticing the error. You log on to your account at ni.com and locate the topic in question (which has been posted online in HTML form). You click the Comment button and post a quick note that details the problem with the topic.
Two days later you receive an RSS notification saying that someone has replied to your comment. It turns out a small engineering company in the Midwest was using the same product incorrectly because the user manual is insufficient or erroneous. But, thanks to your correction, they went in a different direction and the project is moving ahead full steam. Over the next couple days you get several more replies from other users. Some ask questions about your post, and you reply. Some post scenarios where you have to do things differently than the manual describes. Others point out inaccuracies that you yourself had not noticed. A developer explains why certain quirks are present and announces that he's filed a request to change the behavior.
A year later, all pertinent information has been incorporated into the next version of the user manual, and even more people benefit. You gain self-satisfaction and a reputation as a trustworthy expert who knows the inner workings of LabVIEW. Other users gain insight into how to use a particular feature. R&D, sales, and marketing folks gain evidence about how customers use their features. Marketing gains site traffic and credibility. (IT gains another server to handle the load.) Technical writers gain useful, valuable content that trickles down to other users who don't check ni.com. NI gains a positive reputation and tangible financial benefit.
All for nothing.
It could happen, right?
This is how I imagine documentation working, except I don't have to imagine it anymore. What Microsoft has done is create an open environment for users to collaborate based on shared experiences. Similar to Wikipedia, the initiative might expose flaws in their documentation, but I imagine the overall gains (as described above) far outstrip that small setback. They are embracing Web 2.0. And MS isn't alone. Other products have similar functionality for their documentation.
NI has already launched community.ni.com which is a effort to leap into Web 2.0. On this site, users can submit VIs, comment on them, trade tips about them, rate them, and otherwise collaborate. I envision something happening for LabVIEW and other NI documentation.
June 12, 2006
May 23, 2006
MarComm vs. TechComm
At my last job, I did a lot of marketing writing in addition to technical writing. This situation arose mainly because my last company had ~25 employees at the time, so we were all required to wear many different hats. Ask me sometime about my adventures in painting the bathroom.
I'd had classes in "professional writing" but no formal training in writing press releases or ad copy, although I did take a class in PR. Yet I found myself drafting these kinds of documents and reviewing them with my boss. What I found especially amusing was inventing quotes that the company president was supposed to have said. I guess up until then I'd assumed that quotes in press releases were, well, real.
It's interesting to me because advertising is seemingly in my blood: my uncle has a long history of corporate marketing positions and is now a freelance marketing consultant. My grandfather was an advertising guru as well, and I have a cousin who's a freelance ad designer (formerly employed at GSD&M).
Marketing might run in my blood but not in my brain. After several PR drafts and other non-tech-writing endeavors, I realized that although I enjoyed the theoretical implications of persuading people to pay attention to my company (with their brains, wallets, or both), I didn't enjoy the actual practice of persuasion. Technical writing suits me much better. I would rather dig deep into how a widget works and explain its operation to people than persuade people that purchasing this widget will solve their problems and make life complete.
As a tech writer, I interact with marketing folks on a regular basis, although perhaps less regularly than some other tech writers working on newer or more established projects. The marketing folk and I come from very different backgrounds but the core is the same: solid and effective communication. It's just that "effective" means something different for each of us. For me, "effective" means "the customer is successful in using the product to meet their needs or solve a problem." For them, "effective" means "the potential customer is made aware of our product and/or turned into an actual customer." Maybe Colin can provide some more insight here.
As much as I am not interested in marketing communication, the disciplines converge when I speak to college students in PR classes (for recruiting purposes). Although these students write all day long, they may not have heard about technical writing as a career option. So I have to do a little marketing communication (presentations, hand-outs, one-on-one chats, etc.) in order to make them aware of the opportunity. Perhaps if I were a better marketer and/or more effective at selling a career in technical writing at NI, we would have gotten a resume or two. As it is, I think we were pitching the wrong product to the wrong audience.
Additionally, sometimes I find myself editing bits and pieces of outbound marketing communication from our marketing people here at NI; typically it's been a little newsletter blurb about one of our product releases. The markeing people are not required to use us as editors as they have a different style that we do, but sometimes it might help a new or transitioning marketing person to get the tech writer's perspective. In these situations, I really have to hold myself back from going overboard with the red pen (virtual or real) and remind myself of the differences between marcomm and techcomm.
Whether you're communicating what a product's features are, or communicating how to use those features, both jobs come down to the same base: effective communication that achieves the goals you want.
I'd had classes in "professional writing" but no formal training in writing press releases or ad copy, although I did take a class in PR. Yet I found myself drafting these kinds of documents and reviewing them with my boss. What I found especially amusing was inventing quotes that the company president was supposed to have said. I guess up until then I'd assumed that quotes in press releases were, well, real.
It's interesting to me because advertising is seemingly in my blood: my uncle has a long history of corporate marketing positions and is now a freelance marketing consultant. My grandfather was an advertising guru as well, and I have a cousin who's a freelance ad designer (formerly employed at GSD&M).
Marketing might run in my blood but not in my brain. After several PR drafts and other non-tech-writing endeavors, I realized that although I enjoyed the theoretical implications of persuading people to pay attention to my company (with their brains, wallets, or both), I didn't enjoy the actual practice of persuasion. Technical writing suits me much better. I would rather dig deep into how a widget works and explain its operation to people than persuade people that purchasing this widget will solve their problems and make life complete.
As a tech writer, I interact with marketing folks on a regular basis, although perhaps less regularly than some other tech writers working on newer or more established projects. The marketing folk and I come from very different backgrounds but the core is the same: solid and effective communication. It's just that "effective" means something different for each of us. For me, "effective" means "the customer is successful in using the product to meet their needs or solve a problem." For them, "effective" means "the potential customer is made aware of our product and/or turned into an actual customer." Maybe Colin can provide some more insight here.
As much as I am not interested in marketing communication, the disciplines converge when I speak to college students in PR classes (for recruiting purposes). Although these students write all day long, they may not have heard about technical writing as a career option. So I have to do a little marketing communication (presentations, hand-outs, one-on-one chats, etc.) in order to make them aware of the opportunity. Perhaps if I were a better marketer and/or more effective at selling a career in technical writing at NI, we would have gotten a resume or two. As it is, I think we were pitching the wrong product to the wrong audience.
Additionally, sometimes I find myself editing bits and pieces of outbound marketing communication from our marketing people here at NI; typically it's been a little newsletter blurb about one of our product releases. The markeing people are not required to use us as editors as they have a different style that we do, but sometimes it might help a new or transitioning marketing person to get the tech writer's perspective. In these situations, I really have to hold myself back from going overboard with the red pen (virtual or real) and remind myself of the differences between marcomm and techcomm.
Whether you're communicating what a product's features are, or communicating how to use those features, both jobs come down to the same base: effective communication that achieves the goals you want.
May 1, 2006
Changing Expectations
I've been working at NI for a little over a year now, and I'm beginning to realize that working for this documentation team has raised my expectations any time I hit a Help button in any program. Raised my expectations to my benefit and aggravation!
The truth is, not every company that writes software has the ability to, or the willingness to, create a comprehensive Help like I think we do at NI. Tooting my own horn? Maybe a little. But even though we haven't produced a "perfect Help" for LabVIEW yet, we have a lot of folks here working hard every day to improve the supporting documentation in usability, scope, and detail. We're definitely some of the best Help I've seen.
On the other hand, just as I've learned to click the Help button in other programs expecting answers to my questions, I think a lot of other people have learned NOT to click the Help button in LabVIEW. Their expectations are that they won't find answers in the LabVIEW Help because they've been disappointed so many times before with other help systems.
In fact, today we had a tech support person bring us a printed copy of a web page with a topic that he said should go in the LabVIEW Help because it was so useful to the customer. Turns out, he'd printed a topic from the LabVIEW Help we just recently posted to the Web!
Funny. Frustrating. The incident might say more about people's comfort level with the Web as the ultimate documentation resource than about their confidence in the LabVIEW Help. Then again, it might also show that we need to continue marketing our own Help - even within the company.
I'd be curious to read more examples of great online help. Suggestions, anyone? I've got a list as long as my arm with bad examples...
The truth is, not every company that writes software has the ability to, or the willingness to, create a comprehensive Help like I think we do at NI. Tooting my own horn? Maybe a little. But even though we haven't produced a "perfect Help" for LabVIEW yet, we have a lot of folks here working hard every day to improve the supporting documentation in usability, scope, and detail. We're definitely some of the best Help I've seen.
On the other hand, just as I've learned to click the Help button in other programs expecting answers to my questions, I think a lot of other people have learned NOT to click the Help button in LabVIEW. Their expectations are that they won't find answers in the LabVIEW Help because they've been disappointed so many times before with other help systems.
In fact, today we had a tech support person bring us a printed copy of a web page with a topic that he said should go in the LabVIEW Help because it was so useful to the customer. Turns out, he'd printed a topic from the LabVIEW Help we just recently posted to the Web!
Funny. Frustrating. The incident might say more about people's comfort level with the Web as the ultimate documentation resource than about their confidence in the LabVIEW Help. Then again, it might also show that we need to continue marketing our own Help - even within the company.
I'd be curious to read more examples of great online help. Suggestions, anyone? I've got a list as long as my arm with bad examples...
March 15, 2006
It's Not All Pencils and Paper
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."
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 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.
Subscribe to:
Posts (Atom)