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.
That does sound like a monstrous task. I?d like to understand it a bit
more before trying to provide some detailed suggestions.
The way that you first described the task sounded very reasonable and a
laudable approach - document the ?whole product? using a task centered
approach, from purchase to install to use to upgrade or dispose.
>My team has been "tasked" with a very specific analysis of our products.
>What this means is that each writer will take a component from each
>product and document EVERYTHING about it: how it works, how to install
>and configure it, etc
But the next part threw me. Why would they want a writing team to develop
something like state diagrams for the product? It sounds more like a
verification activity and I don?t have a clear idea of how this
information would be used after it has been produced, other than as a
very, very formal way of specifying the product for integration or
>Each writer must create a list of all possible things each component can
do, and then create end-user documents.
I have carried out activities similar to the first part of your
description using task analysis. It?s a concise, clear way of outlining
the steps that users perform. One of the very aspects of the method that
you might find very useful is that you can work with the stakeholder to
define exactly what level of detail they want you to go into ? or do the
full analysis down to commands and keystrokes but limit how much
information you make available in different document types. For instance
you could have an overview document outlining the high level tasks of
product use, then sub-documents that describe each sub-task.
The aspect of detailing everything about every component can be handled by
creating your initial task analysis then re-working it with key experts
such as people in sales, marketing or development. That kind of review
will give you the coverage you?ve been tasked with; and might even help
with identifying potential improvements to user guides.
I think that this approach fits the mindset of many technical writers and
is an easy way of communicating out to all sorts of readers ? from
marketing to developers.
It sounds like you?re constrained in the editing tools that you can use.
I'd suggest that you take a look at TaskArchitect. It?s designed to make
the process of carrying out task analysis faster and easier and will help
your communication out through providing a variety of textual and visual
outputs as well as export to standard industry tools. If you?d like to
take a look, there?s more information about the tool at
Maybe you could provide more detail on the constraints on your choice of
editing tools and that troubling second part of the task ? documenting
everything that a user could do. That last part reminds me of a
Japanese verification activity called ?bully testing?
? they would test every conceivable combination of commands just to see if
they could break the product. Is that the sort of thing you?re being asked
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.