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.
Your post inspires me to want to delve into the origins and history of
tech writing.
It seems odd that tech writing has evolved from probably a simple
beginning of written communication to the point where the writer is now
intimately involved with user experience design. That's not a bad
thing, it's just curious.
What qualifies a writer to perform this role? Is he/she the advocate of
the ordinary person? Is the writer somehow more "human" than the
developer, and therefore able to talk to the user in that person's
cognitive language?
I remember the days when you had to fight to get a word change into the
UI -- writers were not allowed to contribute in any way to the
interface, even from a language standpoint.
Now our ideas are welcomed, even solicited, regarding functionality,
user experience, usability, interaction design, navigation design,
screen layout, information architecture, and the rest of it.
Innovators aren't always good writers, and writers aren't always good
innovators. If our role largely makes procedures obsolete, then what
*is* our role?
Meantime, have a great weekend, all! :)
Steve
-----Original Message-----
From: techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Chris Despopoulos
Sent: Friday, October 30, 2009 5:39 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Doc Design and Conventions
Comments inline...
#A few points, just random thoughts:
#
#* The writer in question (yours truly) wasn't really "floundering," or
#at least not unreasonably. Project was to document a product that had
#an acknowledged multi-year learning curve. Delayed understanding was
#unavoidable.
#
I didn't mean any offense... sorry (chagrin). The users probably
aren't "floundering" either. More likely they're grumbling about not
getting the information they really need when they finally find the
topic. Not in *your* work per se, but in too many docs. Too we see
pages devoted to stuff they already know, and not enough time (or money)
to research and cover the stuff they need to know.
#* DITA and good Information Architecture actually accomplishes what you
#suggest about dialog boxes. High-level task topic gives the barebones
#basics, no description of fields or values; then a separate reference
#topic lists these in a table. But I like what you're saying about
#taking task orientation to a higher level. It rocks!
You're absolutely right -- DITA and other modern approaches imply an
ordering of tasks. I think I'm complaining about how far down that food
chain we have to go. Is there a point where we can say, "You understand
the task at hand, now just make these settings and click Do It"? Or
must we list each setting as a step in a procedure?
#
#* I know your point was that it's better for the writer to do the doc
#*after* the unifying "Aha!" experience than before. But there's no
#guarantee that the writer's crystal clear vision will be apprehended by
#the user, even with the clearest and simplest of treatments. To
#overdramatize, the Zen master cannot "transmit" satori to the student.
#Unfortunately, insight has to be earned.
As I recall, there's a Koan where the master does transmit satori, but
the student loses a finger in the bargain. Maybe we should sharpen the
edges of our CDs...
#
#* Idea of getting the writer into the process at the very beginning or
#at least very early is ideal. That works great in start-ups and
smaller #companies, but pretty tough in the complex behemoths. I don't
work at #IBM or Sun, but I can just imagine jumping onto one of their
projects #and I would bet that most writers there would share your dream
but don't #often get to do it. Great in principle, admittedly rare in
practice.
#
Actually, I worked for a *very* large company (the local police managed
5:00 traffic at the parking lot every day), and I did get in on the
projects at the start. But then we had the benefit of Agile. Mind you,
I had to participate in many scrums at once, but I had the pleasure of
being involved early. It really works, it's really more efficient, and
you really contribute *much* more than just producing pages. Another
topic, I guess. But I'll say a large company can get the authors into
the project early if it wants to.
#* What you say about use cases is very interesting and stimulates other
#thoughts. Maybe for another post.
#
#* True that things are very different since the advent of the
#task-orientation mantra. It makes you wonder what we really need to
#document anymore, but I believe you've answered that with the idea of
#use cases and conceptual information. But one question: Don't use
#cases suggest tasks? If I want to assemble a bicycle, aren't you going
#to give me a step-by-step procedure on like a foldable sheet?
#
I'm not saying we should drop task orientation. I'm saying we should
reconsider what it means. At what level do you find the task? At what
level do you find details that can be handled in a blob of some sort?
Just because the heading starts with a gerund, is it a task? Just
because it doesn't, is it not? If you describe the task and background
concepts up front, are you giving the user too much information? Where
are the dreaded inner workings, vs. honest need-to-know information? Is
there a call for reference material after all? Is *everything* a task,
or are there other types of information we could transmit? Why do we
have a dictionary, a thesaurus, and a host of grammar texts for users of
the English language -- if complexity of the subject inevitably means
task-orientation will be insufficient, at what degree of complexity does
this happen? And how complex is our software today?What would happen to
English over the years if we only had grammar texts?
#* Some of the things you've said suggest stepping back from the doc and
#abstracting out to what it is we're really trying to do with these
#things. What's software for, what are the machines for, what does all
#this stuff do that we couldn't do before it was invented? Automation,
#taking over menial or repetitive tasks, doing things that use low-level
#human skills. Actually, some of it is quite complex so you can't
really #say that. Computers do things that would have taken many years
without #them and in some cases could never have been done. So in some
ways the #machines and software replace the activities of the mind. ...
We're #losing touch with the tactile world. Some people still write
longhand #just for the sensation. Computer use replaces social
interaction but #then you have social media and networking that wasn't
possible before.
#But you're still not really talking to somebody face to face, seeing
#them, hearing them, experiencing their presence. Ultimately you wonder
#what's going to be left for us to do.
#
#But for right now, tech writing's not a bad profession. :)
Every once in a while I stop to wonder, if we're so smart then why are
we all slaves to the network? I mean, we feed it, we fix it, we flatter
it, we kowtow, and we live in fear of it breaking down. There's a
bargain going on where we do stuff for it so it will do stuff for us.
I'm not so sure we're getting the better end of that bargain...
#
#Steve
#
#PS - I forget where I read it but Donald Norman once suggested that the
#user manual be written before the product was even designed. That's
#almost like screenwriting. A heck of an idea! On the other hand,
#you're limited to the writer's vision of how something should be used,
#which could be constrained by what he/she is already familiar with in
#the world. I mean, could a writer have written the iPod user manual
#before the thing was developed? I doubt it, unless that writer was
#incredibly visionary.
#
Sounds great! Let's do a start-up.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
