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.
Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
Subject:Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, From:Robert Lauriston <robert -at- lauriston -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 6 Nov 2009 08:37:45 -0800
You seem to be conflating content and delivery, as well as task and
topic orientation.
I've never worked on an application that needed only instructions on
performing common tasks. Typically they've also needed conceptual
overviews explaining the workflow and so on, a task-oriented
administrator's guide, hands-on tutorials with sample projects, and
reference materials.
That the users need all those things does not necessarily mean you
deliver them as separate documents--most often it seemed most
convenient for users to have them all in one extensively
cross-referenced document, which can be delivered both as online help
and PDF. The most common exception was separating out administrator
material for security reasons. Cost has never been a factor in
deciding how many deliverables to create.
We already have systems that can customize deliverables based on the
user's permissions, preferences, and so on. Eclipse for one can do
that.
On Fri, Nov 6, 2009 at 7:57 AM, Chris Despopoulos
<despopoulos_chriss -at- yahoo -dot- com> wrote:
> 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: http://www.doctohelp.com/
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. http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
