July 27, 2005
July 22, 2005
One of the most striking differences, in my opinion, between Windows 3.1 and Windows 95 was the taskbar. Windows 3.1, if you recall, relied mainly on the Alt+Tab keyboard combination to switch between programs that were running at the same time. Sure, you could use the program's minimized icon on the desktop, but then you had to minimize the window and double-click on the icon. While Windows 3.1 was designed for multitasking, the UI for switching between tasks was not as obvious as the taskbar of Windows 95 made it to be.
I remember the first time I saw my dad dial up to the World Wide Web. I think it was early 1995 or late 1994. He had to dial up the ISP using one program, which I vaguely recall as having the word "Winsock" in the name. After that program connected to the WWW, he had to Alt+Tab back to the Program Manager and launch NCSA Mosaic to actually browse the web. I remember thinking at the time that switching between the two programs in that fashion seemed unintuitive. The notion seems quaint now, with the advent of the taskbar and its glorious reminder that we can run as many programs at once as our computer's RAM can handle.
I mention all this multitasking nonsense because of an article I caught on CNET today. I've seen a bunch of these articles appear over the past couple years that describe frazzled executives and workers who can't cope with "information overload." This CNET article sounds the typical alarm about people who need to "unplug." But I think that if they talked to a younger generation of workers, perhaps those who are just entering the workforce after college, they would find that multitasking is just a fact of life, and perhaps a source of pride.
Although I am old enough to remember the pre-Internet days of communicating, I pretty much grew up using IM, email, and all the multitaskable tools of which the article speaks. I was one of the first people I knew to get broadband access in late 1998 (my mom was tired of picking up the phone and hearing those wonderful modem-screeching noises). Playing lots of video games enabled me to pay attention to many things at once. And, although I lament the fact now, watching MTV and other rapid-fire television programming left my attention span able to cope with short barrages of intense information.
This familiarity with multitasking led to my acceptance of the idea as normal. I guess I can't imagine not multitasking or not being available by cell phone/IM/etc. The workplace has changed so much over the past 15 years, but because I only entered the workforce two years ago, I slid easily into a job that required me to wear many different hats at all hours of the day. Even here at NI, being a technical writer definitely tests my ability to multitask, but I find myself almost looking forward to the challenge.
Another pertinent effect of being familiar with multitasking is that I learned very early on how to take time out for myself to unwind or unplug. That's why I can't really relate to the CNET article. Those interviewed stressed the problems they've had adjusting. But I spent my entire pre-work life "adjusting," although I didn't know it at the time. So that's why I'm comfortable with the thought of multitasking 8 or 9 hours a day: I know how to do it and I also know when to take a break and chill for a bit. I imagine it would be hard to adjust to such a multitasking-oriented workplace if you were not already used to being reached by IM, email, cell phone, etc. anywhere you went.
Maybe as more people raised similarly enter the workforce and become managers and executives, we'll see articles and studies like these disappear because we'll all have become used to these things called computers and how they keep us in touch with various facets of work at the same time. Of course, technology moves at a rapid clip, and it's all we can do just to keep up - so it's possible that what I now consider multitasking will seem as quaint as the notions I espouse in the first two paragraphs. I'm sure the next generation will have its own set of workplace issues to get acquainted with.
On a completely unrelated note, I find it amusing when software developers identify themselves with the software. Example: "The code I wrote pops up an error when a user tries to do that" becomes "I pop up an error when the user tries to do that." I know it's shorthand (or shortmouth in this case), but I always like to imagine one of our developers knocking on a customer's door and holding up a sign that reads "ERROR!" in big red letters. Of course, now when someone asks me about a help file I've written, I say "I have a paragraph about that" or "I talk about that here." The notion of "owning" help files is in itself something I've thought about recently. Maybe I'll make that the subject of my next post :-)
On an even more completely unrelated note, this is pretty sweet.
I remember the first time I saw my dad dial up to the World Wide Web. I think it was early 1995 or late 1994. He had to dial up the ISP using one program, which I vaguely recall as having the word "Winsock" in the name. After that program connected to the WWW, he had to Alt+Tab back to the Program Manager and launch NCSA Mosaic to actually browse the web. I remember thinking at the time that switching between the two programs in that fashion seemed unintuitive. The notion seems quaint now, with the advent of the taskbar and its glorious reminder that we can run as many programs at once as our computer's RAM can handle.
I mention all this multitasking nonsense because of an article I caught on CNET today. I've seen a bunch of these articles appear over the past couple years that describe frazzled executives and workers who can't cope with "information overload." This CNET article sounds the typical alarm about people who need to "unplug." But I think that if they talked to a younger generation of workers, perhaps those who are just entering the workforce after college, they would find that multitasking is just a fact of life, and perhaps a source of pride.
Although I am old enough to remember the pre-Internet days of communicating, I pretty much grew up using IM, email, and all the multitaskable tools of which the article speaks. I was one of the first people I knew to get broadband access in late 1998 (my mom was tired of picking up the phone and hearing those wonderful modem-screeching noises). Playing lots of video games enabled me to pay attention to many things at once. And, although I lament the fact now, watching MTV and other rapid-fire television programming left my attention span able to cope with short barrages of intense information.
This familiarity with multitasking led to my acceptance of the idea as normal. I guess I can't imagine not multitasking or not being available by cell phone/IM/etc. The workplace has changed so much over the past 15 years, but because I only entered the workforce two years ago, I slid easily into a job that required me to wear many different hats at all hours of the day. Even here at NI, being a technical writer definitely tests my ability to multitask, but I find myself almost looking forward to the challenge.
Another pertinent effect of being familiar with multitasking is that I learned very early on how to take time out for myself to unwind or unplug. That's why I can't really relate to the CNET article. Those interviewed stressed the problems they've had adjusting. But I spent my entire pre-work life "adjusting," although I didn't know it at the time. So that's why I'm comfortable with the thought of multitasking 8 or 9 hours a day: I know how to do it and I also know when to take a break and chill for a bit. I imagine it would be hard to adjust to such a multitasking-oriented workplace if you were not already used to being reached by IM, email, cell phone, etc. anywhere you went.
Maybe as more people raised similarly enter the workforce and become managers and executives, we'll see articles and studies like these disappear because we'll all have become used to these things called computers and how they keep us in touch with various facets of work at the same time. Of course, technology moves at a rapid clip, and it's all we can do just to keep up - so it's possible that what I now consider multitasking will seem as quaint as the notions I espouse in the first two paragraphs. I'm sure the next generation will have its own set of workplace issues to get acquainted with.
On a completely unrelated note, I find it amusing when software developers identify themselves with the software. Example: "The code I wrote pops up an error when a user tries to do that" becomes "I pop up an error when the user tries to do that." I know it's shorthand (or shortmouth in this case), but I always like to imagine one of our developers knocking on a customer's door and holding up a sign that reads "ERROR!" in big red letters. Of course, now when someone asks me about a help file I've written, I say "I have a paragraph about that" or "I talk about that here." The notion of "owning" help files is in itself something I've thought about recently. Maybe I'll make that the subject of my next post :-)
On an even more completely unrelated note, this is pretty sweet.
July 20, 2005
Want to see how we write? You can now search our HTML and PDF help online. Currently only core LabVIEW deliverables are up; these don't include any add-ons (like my Control Design & Simulation stuff). I'm not sure if or when those docs will go up, but I don't see why we wouldn't post them. Also, since the linked web page says " NI Products" and not "LabVIEW," I assume that other product manuals will end up here as well.
If you notice any issues, be sure to report them. You can contact the web team or leave a comment here and I'll get the message to the appropriate people.
If you notice any issues, be sure to report them. You can contact the web team or leave a comment here and I'll get the message to the appropriate people.
July 14, 2005
What features are self-evident? What features really need documentation? If a feature does need documentation, how much documentation does it need and what level of prominence should a feature have? These are questions I have to ask myself many times throughout a document's life cycle.
During the planning phase of development, it's my job to gather the proposed features together and determine how each one will impact the documentation set. For example, Feature X might require updates to the online help, a bullet point in the readme.html file, a new graphic on page 11-3 of the user manual, and revisions to existing paragraphs that are related to the new feature. To determine the documentation impact, I talk with the developers and ask them what users need to know about the feature. From that, I can get an idea of where a feature needs to be mentioned. As the feature morphs from planning to implementation, the documentation is inevitably affected, and I have to stay alert to see what's going on.
Sometimes I immediately think that a certain feature, UI change, or other small tweak does not need any documentation. This is especially true when I use a specific term while explaining the operation of a function or dialog box. It's standard practice to ask the developer if I can expect a user to know, for example, what rate-monotonic scheduling is. But a lot of the time it comes down to what I think the users needs to know. I realized the other day that I make decisions like these all the time, and I'm effectively imposing my personal biases, assumptions, and viewpoints on the user. I'm basically saying "Oh, anyone can figure this out, it's pretty self-explanatory." Is that really the case, though? I'm not sure there's a definitive answer to that question.
For one thing, I can never be sure who's going to use my products. (I say "my" like I own it somehow, but you know what I mean.) Some engineering firm might have an in-house LabVIEW developer who knows how to operate the Simulation Module by heart. But if this person is out for a week, or quits, their work might get passed off to someone who's never seen the product before. Or there might be a division of labor scenario where one person acquires a plant model, another designs the controller, another designs the simulation, another implements everything on a real-time target, etc. In these situations, taking the time to explain certain terms, phrases, or features can (hopefully) help the next person in line do their job better.
Another consideration in deciding what's obvious or not is the layout of the UI. After watching people test one of my products, I noticed that the order of buttons on a dialog box can have a big impact on whether or not a user can easily accomplish a certain task. Even something as seemingly insignificant as a button label can help users step through a task. Fortunately, as tech writers at NI we’re encouraged to suggest alternative methods of dialog box layout and navigation. We step back from the product, clear our heads of everything we know about it, and act like a first-time user who knows what they want to accomplish with the product but is unfamiliar with its layout and/or operation. In fact, a suggestion I had for the Simulation Interface Toolkit will end up being a feature at some point.
Anyway, the first point of contact is the developers, who can tell me how they want a user to use the feature. As I said before, they can also tell me about any industry-standard terminology. The other LabVIEW tech writers are definitely another resource, since most of them have been working on LabVIEW and/or its add-ons for quite some time now. A lot of times, I or another writer will cite precedent and consider the issue closed.
We work closely with the product support engineers, who in turn work closely with customers, to find out whether a certain explanation or feature might be helpful. The style guides to which I adhere also contain information on issues like these. Finally, I’ve found that interns / co-ops can have some useful insights into products they haven’t used before.
If none of these resources produce any solid case for or against the documentation or explanation of a piece of information, the decision lies with me, and that’s where my own worldview comes in to play. And while I’m not pretending it’s a giant weight on my shoulders, the fact is that I’m the main gatekeeper for what users see in terms of help for a particular product. That is, if they read the help in the first place :-) As I gain more experience with the Control Design & Simulation products and the ways in which the users like to accomplish tasks with these products, I'll be able to make more informed judgement calls on the level of documentation / explanation for a particular feature.
Ultimately, I suppose, the goal is to design software with features so intuitive they don’t require any documentation. If that ever happens, though, I suppose I'd be out of a job :-)
During the planning phase of development, it's my job to gather the proposed features together and determine how each one will impact the documentation set. For example, Feature X might require updates to the online help, a bullet point in the readme.html file, a new graphic on page 11-3 of the user manual, and revisions to existing paragraphs that are related to the new feature. To determine the documentation impact, I talk with the developers and ask them what users need to know about the feature. From that, I can get an idea of where a feature needs to be mentioned. As the feature morphs from planning to implementation, the documentation is inevitably affected, and I have to stay alert to see what's going on.
Sometimes I immediately think that a certain feature, UI change, or other small tweak does not need any documentation. This is especially true when I use a specific term while explaining the operation of a function or dialog box. It's standard practice to ask the developer if I can expect a user to know, for example, what rate-monotonic scheduling is. But a lot of the time it comes down to what I think the users needs to know. I realized the other day that I make decisions like these all the time, and I'm effectively imposing my personal biases, assumptions, and viewpoints on the user. I'm basically saying "Oh, anyone can figure this out, it's pretty self-explanatory." Is that really the case, though? I'm not sure there's a definitive answer to that question.
For one thing, I can never be sure who's going to use my products. (I say "my" like I own it somehow, but you know what I mean.) Some engineering firm might have an in-house LabVIEW developer who knows how to operate the Simulation Module by heart. But if this person is out for a week, or quits, their work might get passed off to someone who's never seen the product before. Or there might be a division of labor scenario where one person acquires a plant model, another designs the controller, another designs the simulation, another implements everything on a real-time target, etc. In these situations, taking the time to explain certain terms, phrases, or features can (hopefully) help the next person in line do their job better.
Another consideration in deciding what's obvious or not is the layout of the UI. After watching people test one of my products, I noticed that the order of buttons on a dialog box can have a big impact on whether or not a user can easily accomplish a certain task. Even something as seemingly insignificant as a button label can help users step through a task. Fortunately, as tech writers at NI we’re encouraged to suggest alternative methods of dialog box layout and navigation. We step back from the product, clear our heads of everything we know about it, and act like a first-time user who knows what they want to accomplish with the product but is unfamiliar with its layout and/or operation. In fact, a suggestion I had for the Simulation Interface Toolkit will end up being a feature at some point.
Anyway, the first point of contact is the developers, who can tell me how they want a user to use the feature. As I said before, they can also tell me about any industry-standard terminology. The other LabVIEW tech writers are definitely another resource, since most of them have been working on LabVIEW and/or its add-ons for quite some time now. A lot of times, I or another writer will cite precedent and consider the issue closed.
We work closely with the product support engineers, who in turn work closely with customers, to find out whether a certain explanation or feature might be helpful. The style guides to which I adhere also contain information on issues like these. Finally, I’ve found that interns / co-ops can have some useful insights into products they haven’t used before.
If none of these resources produce any solid case for or against the documentation or explanation of a piece of information, the decision lies with me, and that’s where my own worldview comes in to play. And while I’m not pretending it’s a giant weight on my shoulders, the fact is that I’m the main gatekeeper for what users see in terms of help for a particular product. That is, if they read the help in the first place :-) As I gain more experience with the Control Design & Simulation products and the ways in which the users like to accomplish tasks with these products, I'll be able to make more informed judgement calls on the level of documentation / explanation for a particular feature.
Ultimately, I suppose, the goal is to design software with features so intuitive they don’t require any documentation. If that ever happens, though, I suppose I'd be out of a job :-)
July 7, 2005
Two of my products are in beta right now. Both programs are generating feedback to the developers, which is very good of course. But the interesting thing I'm dealing with today is trying to fit new features/tweaks/bug fix documentation items into the existing structure of the documentation set. What I mean is, I've spent the past several months working with the developers and my manager to organize the documentation set in a specific way. (That effort brought its own challenges, which are kind of fun because they represent a larger LabVIEW effort to make the documentation easier to use, but I'll talk more about that in a later post.)
Anyway, now that beta customers' feedback is trickling in, the developers implement certain suggestions and then let me know I need to incorporate the new behavior into the existing documentation. Today I'm challenged to find places for these seemingly random tidbits of information that do not have a defined place in the existing structure. Sometimes I look at a what a developer says and think "Oh, I know exactly where that should go to make the most sense." Today though I've run into at least one beta-generated behavior change that doesn't fit anywhere. I'm reluctant to make a new topic for two reasons: 1) doing so calls the organization of the help file into question, and 2) an entire topic implies that this behavior is extremely important for the user to know, which might not be the case. Besides, a separate topic with one paragraph in it doesn't make much sense. I considered just adding a line to the "Known Issues" section of the readme file, but that implies there is a bug or something, which is not the case.
So part of the problem is that I don't know how much prominence to give to a certain change. Will users run into this situation often enough that this behavior merits its own heading? How will adding that heading affect the layout of the help file? Is this information related to the other information in this help topic? Questions like that. I'm glad that I have the freedom to even ask these questions and figure out answers in my own way. Sometimes, though, I wish I could just have a "Miscellaneous Information" help file with random tidbits of information about certain behaviors. The main LabVIEW Help has set a similar precedent with its "Caveats and Recommendations when doing X" topics, which is along the lines of what I'd like to do, but this particular behavior isn't a caveat or recommendation.
I'll figure out a home for this orphan piece of documentation, though. And in the future, I will look for ways to design more "flexible" documentation that can accommodate these tidbits better. I'm learning a lot from my first betas.
And speaking of random tidbits of documentation, Blogger apparently adds <p></p> tags to each paragraph, even if you don't specify them when editing raw HTML. Is that behavior documented anywhere?
Anyway, now that beta customers' feedback is trickling in, the developers implement certain suggestions and then let me know I need to incorporate the new behavior into the existing documentation. Today I'm challenged to find places for these seemingly random tidbits of information that do not have a defined place in the existing structure. Sometimes I look at a what a developer says and think "Oh, I know exactly where that should go to make the most sense." Today though I've run into at least one beta-generated behavior change that doesn't fit anywhere. I'm reluctant to make a new topic for two reasons: 1) doing so calls the organization of the help file into question, and 2) an entire topic implies that this behavior is extremely important for the user to know, which might not be the case. Besides, a separate topic with one paragraph in it doesn't make much sense. I considered just adding a line to the "Known Issues" section of the readme file, but that implies there is a bug or something, which is not the case.
So part of the problem is that I don't know how much prominence to give to a certain change. Will users run into this situation often enough that this behavior merits its own heading? How will adding that heading affect the layout of the help file? Is this information related to the other information in this help topic? Questions like that. I'm glad that I have the freedom to even ask these questions and figure out answers in my own way. Sometimes, though, I wish I could just have a "Miscellaneous Information" help file with random tidbits of information about certain behaviors. The main LabVIEW Help has set a similar precedent with its "Caveats and Recommendations when doing X" topics, which is along the lines of what I'd like to do, but this particular behavior isn't a caveat or recommendation.
I'll figure out a home for this orphan piece of documentation, though. And in the future, I will look for ways to design more "flexible" documentation that can accommodate these tidbits better. I'm learning a lot from my first betas.
And speaking of random tidbits of documentation, Blogger apparently adds <p></p> tags to each paragraph, even if you don't specify them when editing raw HTML. Is that behavior documented anywhere?
Subscribe to:
Posts (Atom)