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:Doc Design and Conventions From:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 30 Oct 2009 05:38:49 -0700 (PDT)
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.
#
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-
