OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: DOCBOOK: Your replies to Modular Documentation

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC