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: Sat, 7 Nov 2009 17:39:37 -0800 (PST)

Comments inline...

# You seem to be conflating content and delivery, as well as task and
# topic orientation.

I'm so sorry I introduced that word in this thread. Um... Especially in the e-text world, isn't there an implicit "conflation" of content and delivery? When the content flashes or walks across the page, isn't the delivery part of the content? And no, I'm not conflating task and topic orientation. I'm arguing for less emphasis (or let's say a different emhpasis) on task orientation within the topics. Or at least that's my intent.

#
# 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.

You must be a remarkable writer who has always worked for remarkable employers. I have never worked in a position where cost was not a factor in deciding how many deliverables to create. In fact, I'd say the entire history of publishing could be traced by studying the cost factor. It's why we have technological improvements, why we argue these issues, and why efficiency is a big factor in who does and does not get hired. I personally recall the meetings where page count was the driving factor in dropping the reference guide and merging it with the user's guide -- at various companies. Sure, reduced page count is supposed to help the user, but that benefit isn't guaranteed. Bad writing can easily make the docs worse. The only guarantee reduced page count offered in the days of printed pages was lowered cost. Even with e-delivery the same holds true... Fewer pages means management expects fewer writers producing them.

Anyway, I completely agree that users need different types of information, and I do not argue against merging the different types of information in one user's guide. In fact, that's exactly what I'm talking about. By stepping back a level in the detail of tasks and procedures, we make rhetorical and physical room for these other types of information. It's funny... I'm a writer, I'm writing, and I feel so misunderstood. Why do people hire me if I'm this bad at it?

#
# We already have systems that can customize deliverables based on the
# user's permissions, preferences, and so on. Eclipse for one can do
# that.

Do you have examples aside from Eclipse of product docs that exploit this technology? Also, isn't Eclipse help mainly organized around what plugins you have installed and running, and not on roles assigned to user accounts? Eclipse hints at role-based docs, but it's really based on the current state of the software, isn't it?

cud



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

Previous by Author: Re: Doc Design and Convention - to address Gene's take on
Next by Author: Re: Doc Design and Convention - to address Gene's take on
Previous by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
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