This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Modular Documentation


Hello list members - will you tolerate a newbie question or three?

I found information on the 'net leading me to suspect that you may have some
insight into modular (XML-based or object-oriented) documentation.

I ordered Norman Walsh's DocBook publication off of Amazon, but it won't be
here for a few days, then I found this discussion list.

Might I ask for your time and experience to answer a few questions?

My company, a software development shop producing an NT-based app for the
Securities industry, uses the traditional MS-Word docs associated with
waterfall software development. Our base templates (the Business
Requirements, Solution Approach, Functional Spec., SRS, Technical Spec.,
Test Plan, Release Notes, User Guide Update, etc.) are used to document our
projects throughout the SDLC...as I said, software documentation's standard
process for the last twenty years.

Ours is world of constant change; we've grown in five years from six people
to sixty-seven, and expect to double in size this year. There are at any
given time sixty or seventy enhancements in various stages of development,
all of which use several of the documentation artifacts - If the "average"
enhancement project is associated with eight documents, there's maybe 500
documents in play, all of them an instantiation of the base documents. That
just represents software project documents, not all the supporting
enterprise documentation.

As well, we produce our software in a Domestic and an International variant
for Oracle, Sybase, MS-SQL, DB2 databases, and maintain a whole separate
development effort for the Domestic and International variant for one large
internation client.

We have perhaps five client-admin types, 15 VB coders, 5 DBAs, 8 BAs and 3
TWs busily trying to keep this cloud of documentation afloat.

As you have learned, I am told, there is no way using this documentation
paradigm that we can reuse text or screen shots, no way to eliminate
duplication and replication - you know the rest. The bottom line here is
that an awful lot of resource is put into an whole pile of inaccurate
documentation that's of little use to anyone.

I found a paper on the Tenix ship-building project in Australia that, while
not dated, appears to be several years old. That paper introduced me to this
whole paradigm of modular documentation, but doesn't tell me how to do it.
That lead me to a week of research that brings me to you good folk. I hope
to find more modern and more specific info here.

How can a company, no, how can I in particular, being completely naive to
XML, best get started learning and implementing modular documentation in a
small company? I have looked at the DocBooks website, and considered trying
it with something like XMetal, (that's why I ordered the DocBook book...but
from the previews I read it does not appear to tell me HOW to do all this -
just shows me the document structure) and I have talked to sales-types at
Arbortext and Documentum, but really don't know where to go from here. The
two companies named claim to have a solution - but I need to prove this
concept before I can even think of approaching my management for that kind
of money. They are known for only investing in what makes them money, and
pretty much believe that "It ain't real 'till Microsoft does it" (Now
there's a profound thought!)

My idea is to take a small project (I am PM for perhaps 20 enhancements at
any given time) and use that set of documents to teach myself how to do this
and make a proof-of-concept for the company.

Can anyone here tell me how to approach this? Keep in mind that I and our
little company already have what you might call "full-time employment", so I
have to slip this POC in during normal operations.

I believe that if I can pull this off the company will make a commitment and
give me the resources to make it happen...but I have to prove it first.

Any suggestion? Tools? Mentors? Books? Tutorials? Help!

Thanks,

Ed Manley
Senior Business Analyst
Solutions Plus, Inc.
Suite 250
3595 Grandview Parkway
Birmingham, Alabama USA 35243
205-439-5764 Voice
205-439-5760 FAX
emanley@solutionsplus.com





Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]