TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
#Chris Despopoulos wrote:
#>
#> If you have the
#> benefit of all this information, then why shouldn't you share that
#> benefit with your customers? Isn't it necessary for you to know all
#> this stuff (whether through formal channels or a self-inflicted A-Ha!
#> moment) before you can fully understand the product? Why should your
#> audience be any different?
#>
#
#Because your audience isn't trying to document the
#product and most audiences don't care how it works
#or why it works the way it does. Most studies show
#that for end-user products, most people don't even
#look at the documentation at first, they just try to
#start using the product until they get stuck. When they
#do get stuck, they try to find out how to get unstuck
#from the online help or documentation. The user wants
#to use the product, not necessarily to understand it.
#
Is this due to the nature of the user, or the nature of the documentation? (I know... that's a mean question, but I can't help myself...)
#Products that are used by people to produce other
#products (for example, programming languages that
#software developers use to write applications)
#need to be thoroughly documented because the user
#has to understand the underlying product in order
#to understand how to use it. But most commercial
#products do not fall under this category.
#
I was specifically answering a writer who said he had trouble understanding the product until enough exposure to it gave him an A-Ha! experience. The type of information we were discussing is absolutely important for the customer under any and all circumstances... What's the use case for feature X? Can you name a situation where that's too much information for the user? The only question is whether you can assume the use case is known, or do you have to state it explicitly? But without knowledge of the use case, the user will flounder, period. Indeed, the writer was floundering as well until he could assemble the use case on his own.
I'm not saying that users need to know how the underlying data structure limits the GUI and forces them into convoluted work flows. In fact, the whole point of designing software from use cases is to avoid precisely that type of convolution. So I stand by the statement... The writer benefits from use case information, and why not share that benefit with the user?
#>
#> My point is that good coverage doesn't come for
#> free just because the docs are "task oriented".
#> And I also maintain that things have changed
#> considerably since the task-oriented mantra was
#> taken up.
#>
#
#In what way? Online delivery of documentation means
#that we don't have to worry as much about page count
#any more but I don't think it means that end users
#are any more interested in the inner workings of the
#product than they were before.
#
What's changed? Overall computer literacy. I maintain that we still have conventions geared to a 1980's standard of computer literacy. If you feel compelled to describe how to use a text box or a check box, who are you writing to? Even my mother in law would skim past that.
The concept of "end-user product" is at a threshold. It won't be long before the majority of end-user products are web clients into cloudy services. Nobody will want to read about how to use the controls on a web page. What they'll want to know is what the controls actually *do* and what the service does. The vast majority of (if not all) hardware config happens through served pages. People setting up edge servers for a cable service provider definitely don't want to read "Click in the check box to put a check in it" (actual quote). The check box is labeled "Split multicast stream". They want to know how the system splits out a multiplex broadcat (to which codecs, which streams, which ports, etc.), and how to specify/inspect which multicast channel the device is getting. If they come in with a solid sense of the use case, they're a step ahead. From this lower level, if you can describe how the current action relates to the use case (and maybe
others), then you're documenting the product. But if you describe how to use a GUI widget, you're just documenting standard GUI concepts.
Are you looking for one documentation tool that does it all?  Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: http://www.doctohelp.com/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
