Organizing a sprawling doc set?

Subject: Organizing a sprawling doc set?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 13 Jun 2003 11:40:04 -0400


Rebecca Stevenson reports: <<We are currently outlining the doc set for the
new product in development... the requirements are coming in for what looks
like about 30 separate guides, plus white papers. Most of it will probably
be delivered via PDF with some HTML portions, such as the API and database
material... I look at this rapidly metastasizing sprawl of a project and
ask: How is anyone going to find what they're looking for?! If it's not
obviously related to a particular application within the product, I suspect
the answer is "they won't.">>

The first thing to do is to come up with some kind of hierarchy that imposes
order on the chaos. The best hierarchy is one that supports how your
customers are likely to try accessing the information, which is something
you may need to go to the users to find out.

You haven't provided enough information on the "30 guides", but it's
reasonable to expect that people will start their search by product (e.g.,
"I'm using Word") or product family (e.g., "I'm using MS Office"). Let's
assume that's the case, with the caveat that it may be entirely inapplicable
for your guides and you may need to develop a different approach. A typical
approach to setting up directories might be as follows:
Root level: product family
2nd level: product 1, product 2
3rd level: user guides, help files, white papers, marketing docs

That hierarchy provides a starting point for defining your access methods,
since it will support pretty much anything you need: document and version
control, an HTML-based intranet or Web site that uses this structure, and so
on. Obviously, you'll have to tailor this approach to the specific documents
and interrelationships you'll be working with (e.g., rather than product
families, you may be dealing with 30 modules for a single product).

<<We are kicking around the idea of a single, doc-set-wide index. Does this
sound feasible? Logical? Do-able with FrameMaker (and I think we're buying
IXgen)?>>

I can't speak to the software issues, but my impression from following
discussions on techwr-l is that you should be able to create a
cross-document index. It's certainly feasible and useful to do this; I
recall fondly the massive index that came with the documentation for
Interleaf TPS, and referred users to the specific volume and page for each
index entry. (Each volume also had its own index.)

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.

Buy RoboHelp Office X4 by June 13th and receive
$100 mail-in rebate, Plus FREE RoboHelp Plus Pack.

Order RoboHelp today: http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -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.



Follow-Ups:

Previous by Author: Learn a new language?
Next by Author: "Wi-Fi" origin?
Previous by Thread: Re: techwr-l digest: June 11, 2003
Next by Thread: Info on MindLance


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


Sponsored Ads