Re: Beginning topic titles with "How to..."

Subject: Re: Beginning topic titles with "How to..."
From: "Wanda Phillips" <wanda -dot- jane -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 19 Feb 2008 09:35:25 -0800

Let's see... we had a long series of conversations about this when we
moved to DITA, as part of creating this decade's "gold standard" for
our docs.
1) We moved away from How to... and went with the gerund... How to
export became Exporting (what from where).
- How to became a bit of a monster in terms of repetition. With the
gerund leading the title, scanning the TOC became easier (at least for
our test audience of, um, us.).
- I believe there was input from our translation team about this
and they were okay with the gerund (especially since it wasn't really
replacing anything, simply shortening what was already there).
- Our budget bunny loved it (a penny saved is a penny saved and a
feather in my cap.) And when you envision budget bunny, think wizard
Tim and his dire warnings.
- Moving to DITA meant that we smoothed a bunch of *clone and own*
content into shared content. We simplified the titles (in part to make
it easier for us to find the content).

2) We also moved away from About ... About Waveform Data became Waveform Data.

We cluster content:
Waveform Data
- Adding Data Points
- Measuring Two Points on a Single Waveform
- Comparing Points on Two Waveforms

Where we may end up with some need for refinement is in the titles for
concepts and reference. Using the waveform topic to carry on, there is
the basic concept of what the user can graph in a waveform display,
some rudimentary information on where the waveforms appear, and some
navigational aids. Then, there are reference topics which may, as in
the case of waveforms, be on that edge between concept and reference
(and if you think it's hard to define, try defining it for non-tech
writers doing a mass conversion for you, taking old content and
carving it up into DITA topics... madness, I tell you!).

Waveform Data (why, when, where)
- Adding (how)
- Measuring (how)
- Comparing (how)
Waveform Data Options (what in detail)

And then there is the index!

</opinion ... try our rambling reduced product line for a quick
overview of life>

Few people are capable of expressing with equanimity opinions which
differ from the prejudices of their social environment. Most people
are even incapable of forming such opinions.
Albert Einstein

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.


Beginning topic titles with "How to...": From: Deborah Slutzky

Previous by Author: How to and the Gerund Response
Next by Author: Testing an index
Previous by Thread: Re: Beginning topic titles with "How to..."
Next by Thread: Re: Beginning topic titles with "How to..."

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

Sponsored Ads