Creating and Using XML-Based Internal Documents?

Richard Emberson asks: "Once again into the breech...or at least the ground floor in a new startup. This time around, I would like to have all of the Engineering documentation internally online: a unified, internal, CVS-ed, web-based, development organization document tree covering the engineering process, methodology, coding standards, nightly build/test reports, FAQs, new hire information and help pages and the documentation for each project. Recently I've written documentation (on Linux of course) using the Apache XML-stylebook tags, stylesheets, and Ant-base publishing - and I like it. So my questions are: Has anyone done this and, if so, how were the links between documents managed?" Does your workplace use XML in its internal documentation? If so, how well does your system work, and what advice would you pass on to anyone else attempting something similar?

"If you start out with only one project (product), how do you structure it so that when new projects come into existence they can easily be integrated? Are there documentation templates out there upon which I can base the various development documents (like requirements, product development plan, design, coding walk-thru standards, etc.) and not have any of this swell too be so large that no one will be able to produce, maintain or read it?"

Comments

Re:Why Are You Asking Me?

[sphealey]

"My workplace uses a hodge-podge of formats including "special" ASCII text files, Framemaker, HTML and Microsoft Word. Needless to say, it's a mess"

The question I would ask is, Is that because the tools are inadequate? Or because human thinking and creative processes are a mess?

I have worked in highly structured engineering shops where everything is done according to procedure and every document stored in a structured manner (basically using procedures laid down in 1920!). These shops excel at delivering well-scoped projects in understood knowledge realms (the mythical bridge) on-time and on-budget. They do not do so well at handling projects in poorly understood knowledge realms, or projects where the environment and/or requirements changed rapidly.

I have also worked in loose, no-standards, anything goes engineering shops without any structured document/knowledge processes. I wouldn't hire one of these shops to build a bridge on time, but in fast-changing environments they do much better than the first type.

Conclusion: Be sure you understand what type of shop you are supporting before tying everything down with highly structured processes.

sPh