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.
Subject:Re: Best New Thing in User Documentation? From:Phil Stokes <philstokes03 -at- googlemail -dot- com> To:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com List" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 14 Jun 2011 20:14:56 +0700
I have a lot of sympathy with Chris's point of view, though I'd like to offer a few caveats.
There is, I agree, a worrying trend in some quarters that 'text is so last century', and Chris is quite right to point out that you can express a lot richer meaning with greater simplicity and with higher confidence of communicative success in text than any other medium in many situations.
However, there are, as we know, many circumstances where text can – but does not – do the job. Why it does not do the job is part of our ongoing mission to understand - inattentive readers, poor writers, visual learners -- ah the theories and realities are complex but well enough known for me not to have to bang on.
The point is that media like video/screencasting can serve a purpose and can reach audiences more effectively in some circumstances than others.
I'm also not wholly convinced that task-oriented procedures are largely redundant. Most users who need documentation are people who don't know how to do stuff others take for granted. 'Significance' can also be extremely irritating. I don't want someone to keep banging on about why I need to do something when all I want to know is how to do it. OK, I may be a dumBKnut to someone who already knows how to do it, but then everything is easy when you (already) know how...isn't at least on of documentation's major functions to help people who don't know how?
As for social media, I agree: it's all about community, but its the fact that modern technology has made community connections faster and wider that both extends extraordinary power to it and which presents particular dangers to corporate stakeholders if the wrong message starts to get around. It's not like just telling a few people down the local market that you're p**ssed off with your local insurance provider anymore. The causal relationships may not be new, but the speed and depth of the exchange of ideas is, and it needs to be taken account of.
Best
Phil
On 14 Jun 2011, at 18:01, Chris Despopoulos wrote:
> <rant instance=first" mode="curmudgeon">
> RE:
> "Think ATM machine, the self-service check-in kiosks at the airport or the UI
> for Turbo Tax coming up on the display screen of a product."
>
> Do you mean really limited and not very helpful? ATMs work because they do very few things. Airport and other ticket kiosks usually need a human to keep the line moving. Turbo Tax gets on my last nerve -- Why can't they just leave the forms alone, and give me links to the details? Too much Human Factors theory for its own good!
>
> Ok, so apps are increasingly becoming web pages. That means the division between GUI and Doc is blurring. I haven't seen that exploited very well yet.
>
>
> RE:
> "Video documentation and tools like Adobe Captivate get my vote for Best New Thing in User Documentation."
>
> Do the math: V = U/(t*b) where V is value, U is understanding, t is ingestion time, and b is the bits. Video loses out nearly every time. There are indeed some procedures or concepts that yield very well to video... Explaining how a specific reaction transforms a molecule comes to mind. But the vast majority of explanation benefits immeasurably from text. Come on... the ability to collapse experience into a set of 26 (or so) symbols is what has given us the range of technical marvels we enjoy today. Which is more efficient (quicker to take in, less expensive, more portable)... A sign that says DANGER! HIGH VOLTAGE or a 10-second video that shows people getting electrocuted when they touch the wire?
>
> RE:
> Social Media -- There may be some value in it (them?), but it's nothing new. There have been boards and forums since before Al Gore invented the internets. It's called community. I'll also refer you to all the buzz in the early '90s about hypertext literature, where readers would have the *privilege* of participating in authorship. It turns out people prefer authors because they recognize their authority (pun intended) to spin a tale or lay out the facts. Hypertext literature per se devolved into the video game industry. I remember getting booted off of an HT Lit forum because I made the unfortunate observation that the only people interested in HT Lit were HT Lit majors. Ok, so where's HT Lit now? I would look to social media following a similar trajectory, where we recognize the underlying "stratum" (as it were) for what it is -- community -- and very casually (no fanfare, nothing terribly unique going on, it's just people talking to
> each other) use whatever technology is at hand to facilitate it. RoboHelp is a perfect example. For all the commenting that can be done to RH help, I still turn to forums (thank you Peter Grainge) if I need to know anything useful. The community will abandon your docs and establish its own store of information... either that or the docs are well enough written to make that unnecessary. But the community will not fix your docs for you.
> </rant>
>
> So I'm in the camp with (or similar to) help on demand. Look at Eclipse help for example (yet-again, nothing all that new). You load plug-ins, and the docs come along with them. You get the docs that pertain to the plug-ins you are using at the time. Help is *served*, which means there's an entry point for logic and processing at the last minute. The possibility is role-based documentation. Also, follow what's happening with products. The cloud is happening, and products as such are becoming constellations of distributed nodes. Likewise, the docs need to be distributed such that what the reader gets is assembled at the last minute.
>
> <rant instance=second" mode="frothing at the mouth">
>
> I also say the Best Old Thing To Kill is task-oriented documentation. The user community is fully computer-literate by now. No need to describe how a check box works, that's for sure. Beyond that, products are becoming so abstract that what people need to know centers more on significance, and less on specific tasks. Product design has given up on determining the tasks you can perform. It's more that products map out the task domain. Within that you can do whatever you can imagine. It's as though products are becoming visual programming languages -- specialized languages, but languages just the same. How much task-oriented reading do you do to make use of your language? Once you get the basics, probably close to zero. And for English, we're talking about 300,000+ terms. There's no product that comes close to that yet. So the basics for any product are MUCH simpler... need much less in the way of task-oriented discussion.
>
> Aside from a minimal Getting Started section, ditch the tasks and procedures as much as possible, and explain the significance. That's what people need to know... How does this task sub-domain affect MY life? That's what I want to know. Given that, I can see how to make it happen just by looking at the dialog box.
> </rant>
>
> cud
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Phil Stokes BA MA TESOLcert
Language Instructor
Chulalongkorn University Language Institute
Phaya Thai Road
Patumwan
Bangkok
10330
Thailand
Tel: (662) 218-6089
philstokes03 -at- googlemail -dot- com
2551phil -at- gmail -dot- com
philip -dot- s -at- chula -dot- ac -dot- th
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days. http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
