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.
Subject:Delivery formats for big complicated information From:technical -at- theverbalist -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 9 Aug 2004 11:51:44 -0600
Heya Whirlers,
I have a big, complicated document that currently we work with in Word and
deliver as a PDF with hyperlinks, which our users say is good as far as it
goes, but doesn't give them all the info they need, in a way that's easy
to use. So I'm hoping for some suggestions for other formats to present
the info in the document that would be more useful for our users.
The document in question contains a lot of transaction information--for
each transaction it has:
* a description of the transaction
* an example of what it would be used for
* any pre-conditions
* mandatory input
* optional input
* transaction behaviour
* request objects, with hyperlinks to the elements that make up the
objects
* response objects, with hyperlinks to the elements that make up the
objects
Currently
Our users want to know things like:
* which data elements are used in a transactions
* what other transactions use a particular data element
* what ways a transaction can be invoked and the expected behaviour of the
transaction when it is invoked in a particular way
* anything about a transaction that may bite them in the butt
One of the users suggested putting the document into an Access database,
in order to accomplish being able to search for an element in a
transaction, and then on other transactions that use that element. I don't
know anything about Access, so I'd be totally game to learn for to use it
as a info delivery format, but I'm not sure if it's the best way to
deliver what he wants. Does anyone have any other suggestions?
On a related note, there's also some agitation from a senior developer to
deliver our developer-oriented docs, like the Developers Guide, which is
also heavily cross-referenced, in a web page format. I'm OK with this in
theory ('cause it sounds like I'd get to play with more toys to produce
it) but if anyone has any suggestions on whether this is a good idea or a
bad idea or ideas on toy...I mean tools to produce it, I'd love to hear
them.
I'm open to any blue sky suggestions--ya never know, if I ask my boss I
might just get it--so if you were in charge of big, complicated documents
that people want to be able to search and use with more depth than a .pdf
offers, how would you do it?
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
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- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
