Structuring Documentation

Subject: Structuring Documentation
From: Tony Markos <ajmarkos -at- yahoo -dot- com>
To: Dick Margulis <margulisd -at- comcast -dot- net>
Date: Mon, 12 Dec 2005 15:54:41 -0800 (PST)


I was refering to the properly structured
understanding needed for creating task-oriented
end-user documentation on the product. (I generally
assume that end-user documentation should be as task
oriented as possible.) Here, as you point out, what
is needed is a properly structured understanding of
how essential tasks interrelate - not features.

Note: Properly done, software requirements specs are
structured the same way as end-user documentation.

P.S. Notice how I cleverly avoided use of the taboo
"DXD" term - (where X stands for a secret letter) ;-)


--- Dick Margulis <margulisd -at- comcast -dot- net> wrote:

Tony Markos wrote:

And what better way to organize the text than for the
writer to have a properly structured understanding
of the product.

Dick Margulis responds:

....What Sharon and others are saying is something
like this: The structure of a product (a tree that
starts at the whole product and then divides down into
modules, components, parts, and adjustment tolerances,
for example) may be useful for documenting the bill of
materials or the assembly instructions. However, from
the point of view of the user of the product, that
structure is not necessarily meaningful.

A document may follow a tree structure in which the
top node is "all tasks you can perform with this
product" and it
divides down into groups of tasks (accounting,
logistics, order fulfillment)and then into individual
tasks, steps, and options within steps. That may have
nothing to do with the physical or virtual
architecture of the product; it is nonetheless a
structure that is meaningful to the user. Obviously
are other possible structures that may be more
appropriate than this one, depending on the type of
product and the purpose of the document. This is just
one simple example.

Now suppose we start the analysis from the point
ofview of your
favorite methodology, data flow. Again, that might be
a great way to organize development documents, but I
don't think I'd want to use that approach to instruct
a user on the dashboard features or maintenance
requirements of her new car. And yet I'm certainly
going to apply a structure to the document, just not
one that corresponds to the information flow within
the car's control system.
> Dick

Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release.

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Re: Hiring Question: From: Dick Margulis

Previous by Author: Re: Hiring Question
Next by Author: Re: Documenting A Ballet Dance
Previous by Thread: Re: Hiring Question
Next by Thread: Re: Structuring Documentation

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

Sponsored Ads