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.
Pro TechWriter wondered: <<I have a very short time frame to produce
some documentation for some beta software. My thoughts that the
users will need instructions to use the software, with some basic
concepts related to the tasks thrown in. Some folks (um,
"programmers") disagree with that approach. They want high-level
conceptual information instead and some "isn't the product wonderful"
text. They basically said "we don't need no stinkin' steps.">>
It's not clear to me why this is an either/or proposition. Can't you
do both? That's the way I write docs.
Think of it this way: if you give people enough context to understand
where they're coming from and where they're going to, and what tools
they'll use along the way, that's all the conceptual information they
need. If you paint the procedural steps with broad brushstrokes,
they'll generally figure out the details themselves. Remember, this
is "beta" we're talking about: you can refine this crude sketch
later, as the product matures.
For example, consider the following capsule description of a mail
merge: "The purpose of a mail merge is to create personalized letters
by copying contact information from an address database into a
standardized form letter. To do so, you'll need (i) a database of
names and (ii) the form letter. The steps you'll need to follow:
Standardize your database so that all fields that contain the same
type of information have the same name.* Create the form letter. Add
the correct field names from the database at the correct locations in
the form letter. Open the Tools menu and select "Mail merge"; fill in
the necessary details."
* No, really. You'd be amazed at some of the databases I've seen. <g>
Clearly that won't fly as documentation, but on the other hand, it
took me less than 1 minute to write. Give me another 10 and it will
be documentation. <g>
----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
