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: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?
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-
