This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Your replies to Modular Documentation
- From: Jeff Iezzi <jeff dot iezzi at semanticedge dot com>
- To: Ed Manley <edmanley at bellsouth dot net>
- Cc: docbook at lists dot oasis-open dot org
- Date: Tue, 12 Feb 2002 10:06:10 +0100
- Subject: Re: DOCBOOK: Your replies to Modular Documentation
- References: <20020208185802.GA18619@kolon>
- Reply-to: jeff dot iezzi at semanticedge dot com
On 8 Feb 2002, at 16:44, Ed Manley wrote:
> I would like to take a set of three of the documents that I typically create
> for an enhancement; a Functional Specification, a Technical Specification
> and a section extracted from our User Guide, to learn how to do MDM.
>
> I chose these three because they are all extensions of the other - my FS is
> basically an intro, a requirements list (I know, I know...we are looking for
> a tool) and sections containing descriptions and specifications for the
> enhancement, at the functional level, including screen shots, tables, file
> layouts, whatever...
>
> The TS takes almost that exact structure down to the technical level,
> reusing most elements and expanding on some.
>
> Then, the User Guide takes info from the FS and TS, literally a
> copy-and-past operation for screen shots and certain text, button
> click-events, business rules, user actions and so on.
Ed, it sounds like you are well on the way. In my experience, the hardest part
of MDM is designing the structure of the documents before sitting down to
write. Think of the process in the way an architect designs a building: start with
a foundation, build a framework on top of it, finish out the frame, and then add
the trimmings.
In traditional SGML circles, the work of creating the foundation is called
document analysis. Brian Travis (http://www.architag.com/) and Ginny Redish
(http://www.redish.net/) have written some articles about this type of
approach, which is essential to a successful MDM implementation. You can
also look at the Information Mapping technique, which might also help.
> So, we could boil these three documents down to a number of reused sections.
> In fact, these documents are usually created by cutting an element from one,
> pasting it into the next, and perhaps expanding upon it. Of course, many
> enhancements may affect that same screen shot, in different sets of
> documents; That's why the same screen shot might easily exist in fifty
> documents, each shot a different color and size and most likely a different
> release version! Seems to me to be a perfect trial for MDM.
>
> So. Anyone care to offer their complete and detailed ideas on how to go
> about it?
My best advice is to worry about the tools until later. If you are hell-bent on
using XML, there is a learning curve, which may or may not distract you from
the larger goal: doing MDM. Of course, gaining knowledge about the toolset
can also inform your work efforts. In this sense, it may make sense for you to
hire a consultant to help out on the technology side. It depends on the timeline
for your project and your own interest in learning the various tools.
As a final thought, if you want a true guerilla approach, try the following:
1. Take your documents and print each type of document on a different color of
paper. For example, print the Functional Specification on light blue, the
Technical Specification on pink, and the User Guide on yellow. Take a pair of
sissors and cut out the parts of the documents that appear in other documents.
With this simple paper model, you can start to rearrange the contents and get
a better picture of the information flow between the various documents. This
gives you the bird's eye view of the territory and is also much easier to do than
modelling the whole thing in a DTD or a database.
2. For each document type, highlight the sections that are important for each
type as well as the boilerplate text that appears in the document. For example:
the books I write always have a preface that contains a section called
"Typographical Conventions". The information in this section is the same
throughout each book. This is what I call a one-to-many modular documentation
approach: a standardized section is written once and reused in various
publications. By looking at the reusable content within a book, you can
determine whether it is possible to reuse information on a global scale (such as
the above example) or on a local scale. For example, all user guides must have
the same sections in an initial introduction chapter.
3. At this point, you have to look at how you can implement your models using
some type of technology. One approach is to use the master document feature
of MS Word; another approach is to learn DocBook and try to model your
documents using its syntax. For example, in DocBook, you can take two
approaches to sections: numbered sections (<sect1/> and <sect2/>) or
recursive sections (<section/>). I have found that recursive sections are much
easier to use when doing MDM since I do not have to retag sections if I alter or
change the structure of the document.
I realize this is a long-winded reply but I hope it helps a bit. Feel free to contact
me offlist, if you would like to discuss MDM approaches in more detail.
[:>)
"It is difficult to get a man to understand something when his salary depends on his not understanding it."
Upton Sinclair