Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,

Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 6 Nov 2009 07:57:54 -0800 (PST)

I think one problem we all share is related to cost reduction. I remember when a not-to-be-named company bought another ntbn company I worked for. All tech writers had to be interviewed by the consuming tech-pubs mgmt. I asked a question that caused me to find another job... "How do you characterize the difference between help and user guides?" The new mgmt answered, "We don't". I think that's where a large part of the tech world is.

Now I see arguments about precisely this issue... Do we ask the same questions about the users? Should we ask the same questions? Can we use all the answers? And really, the arguments seem to be saying the same thing... It's hard (maybe impossible) to make a one-size-fits-all doc.

Granted, the ROI for separate user's guide, reference, help, and quick-ref was not sustainable. But it turns out there are different approaches to learning, and different needs at different phases in a person's work day. Whether we think there's a one-size-fits-all doc solution is immaterial -- too often we're forced to produce it. The results are clunky, and really bad writing has lots of nooks and crannies to hide in. But practicalities make the issue moot -- where I work there's one doc, it's html & PDF, single source, same content, etc. There's nothing I can do about that.

I think one thing I'm reaching for is permission to reduce emphasis on one size so I can add emphasis to another. Trim the GUI-specific descriptions and describe the effects of user choices more thoroughly. I think most everybody, deep down inside, would like to do that, and many do try. But I also think the conventions of the day sometimes (or oftentimes) get in the way. Shoot, conventions of the day make it difficult to discuss, let alone change the thinking behind user docs.

We may see a technological solution some day. How far away are we from servers that deliver different information to users of different roles? I think the technology is already there, and it's just a lack of money (time) that keeps it from seeing the light of day. But I also think formal analysis could reveal possibilities that influence plain and simple writing for the better. Not only could we get intellectual tools that improve the final product, we would get tools to better evaluate the work in progress. That's how we use the task-oriented directive today... It's an editorial litmus that every user's doc I've worked on has to pass. I'm just saying it's become a bit of a blunt instrument... Let's sharpen it up.

I'm surprised (or maybe not) by the frustration I hear around this issue. If nothing else, it hits a nerve.



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:

Help and Manual 5: The all-in-one help authoring tool. Full support for
team authoring with multi-user editing - both directly and in combination
with VSS-compatible source control systems.

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: Re: Narrative Technical Writing
Next by Author: Re: Doc Design and Convention - to address Gene's take on
Previous by Thread: OT: Periodic table of typefaces
Next by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,

What this post helpful? Share it with friends and colleagues:

Sponsored Ads