[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC