DOCBOOK: Your replies to Modular Documentation

[Ed Manley <edmanley at bellsouth dot net>]

Thanks to everyone who responded! Great stuff!

I know that this is going to be a long row to hoe, but I want to get started
on the right row, so I will ask you to bear with me one more time.

I promise not to flood this list with newbie questions, but I have so many!

As mentioned, I want to do this as a guerilla movement for now, with myself
and perhaps a tech writer working on it - mostly just me to start.

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.

In fact, our documents build on one another so much that my original idea
was to have one long document that lived throughout the project, sort of a
"single-source" indeed. Everybody hated it, and it was impossible to
collaboratively maintain - then I decided on a database, which led me to
MDM.

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.

Now, unless one of the big guys like Arbortext or Documentum wants to give
me a free evaluation for sixty days or so, which is unlikely (though I'm
certainly going to ask!) this means I need to find all the free or cheap
tool Windows-based pieces, install them on my home PC (A five-PC
Win2000/Win98 kludge LAN w/DSL) and go at it.

I don't know Linux, although it's on my list of continuing education topics
for the near future, and my sys-admin at work gets a case of the leaping
fontods every time I mention a Linux documentation server, so I gotta stick
with Windoze.

So. Anyone care to offer their complete and detailed ideas on how to go
about it?

I don't mind getting under the hood - though I am not by profession or
temperament a mechanic, a little grease never scared me. (Not in my younger
days, anyway... Now I'm prone to take the dealership approach.)

I can't offer to pay ya since I am doing this at home on my own till I can
show value, but I will be externally grateful if one or more kind souls
wants to offer to help me with this off-list!

Thanks,
Ed