Slashdot Mirror
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?"
"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
I'll curse the brain dead moron that first suggested using XML for log files for the rest of my days. It is completely unsuited to the task. I have to wade through megabytes of pointless XML every day, searching for errors that are obfuscated by the sheer volume of crap that surrounds them.
"The invisible and the non-existent look very much alike." -- Delos B. McKown
OpenOffice (the equivilant of Mozilla to StarOffice/Netscape) has gone to an XML format for its native format. It's actually several XML files Zipped up in an archive, but you can easily open it and look at the plain XML. Check out the recent builds of OpenOffice. Many of the gripes against StarOffice 5.2 have been resolved.
The Glass is Too Big: My Take on Things
I'd agree. DocBook is excellent, and comprehensive. It is designed for applications like this (technical documentation, etc.), is well supported (built into all ArborText's editors, Frame+SGML, etc.). It is well documented: it has an O'Reilly book written by Norman Walsh. It is very easy to add support for it into stanard text editors: I use xemacs and it works fine (no flames please).
Linking features between documents can be achieved using <olink> and <ulink> tags. The exact details would depend on your repository setup, but the things you want to do are catered for.
Best of luck.