Initial Doc Focus: Concepts or Procedures?

Subject: Initial Doc Focus: Concepts or Procedures?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L Whirlers <techwr-l -at- lists -dot- techwr-l -dot- com>, Pro TechWriter <pro -dot- techwriter -at- gmail -dot- com>
Date: Thu, 24 Jul 2008 08:06:11 -0400

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
***Now available*** _Effective onscreen editing_

Print version:


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.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

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

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 for more resources and info.

Initial Doc Focus: Concepts or Procedures?: From: Pro TechWriter

Previous by Author: Friday files (one day early): putting your Information Architecture skills to good use
Next by Author: Information gathering.....?
Previous by Thread: Re: Initial Doc Focus: Concepts or Procedures?
Next by Thread: RE: Initial Doc Focus: Concepts or Procedures?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads