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?"
they say that office will use XML, however, I doubt that they will use it as file formating as that would put a big leak in thier desktop domination.
:-p)
they will most likly us it for communicating between thier office applications.
of cource they don't tell you that in the press releases, they just say "Office will be moving to XML because we want to support standards" to bad they arn't using XML in a standard way (I know I will get flamed for that last part
I am the Alpha and the Omega-3
CVS is designed for the group. Revision control is handled in Zope primitives, but to be able to back out of something, while diff'ing another thing would be a pain to code for it while maintaining its (admittedly half-decent) UI.
No joke. Start interviewing these information flow officers now. Learn what they can do for you. Getting a sharp young librarian into your business early can be the guide or gardener your jungle will need.
Don't associate librarians with "the library"; there's more of them in businesses than public/school libraries. These are specialists trained in information organization, retrieval, and distribution.
And, being a recession, you may find this investment quite affordable right now.
"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
Doc Book is fine for tech people that can understand and value the benefits of the open nature it promotes. But at the risk of starting a flame war, is there a good editor that provides a WYSIWYG environment for editing the documents?
We have a very common environment of mixed levels of technical expertise. MS-Word is the standard that everyone has, and everyone can use. Currently it is the dictated standard for internal documentation within R&D. The only way to get something in to replace it, is to provide a UI which is at least close to its simplicity of use
Any solutions out there for DocBook?
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
These guys have a single-sourcing documentation app... tech writers enter content into an app that kind of looks like Word or FrameMaker, and then you output to which ever format you like.
http://www.arbortext.com/
It's not quite as simple as I make it sound: you'll have to develop a DTD and Stylesheets... but for the content-people, is easy-breezy.
Don't know how well this falls into the scope of a fully XML-based internal doc environment though.
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've not seen this point of view expressed much on Slashdot, so here goes:
Microsoft have been very clever getting where they are today. One of the principal means they have got there is using the interfaces between different functional elements like keys, to lock customers in, and lock competing technologies out.
XML is a simple, standard way of formatting diverse information types so that it is easy to exchange data between applications, and easy to write programs for. It is brilliant in it's simplicity, and anyone who has studied it will know that it is 'not just another format', but one of the most important standards ever developed in the history of computing.
This represents a huge threat to Microsoft as it threatens one of their main strategies. I believe that everyone in the open source world should learn XML and it's associated standards, and use them as far as possible in their programming work. If, for instance, the open source community adopts DocBook, or Sun's forthcoming XML standard for documents, for all open source word processors, I don't think it will be long before there are so many useful document manipulation applications available that there will be a compelling business reason to move from Microsoft Word to an open source alternative.
Learn XML folks!!!
(There are probably a few reading this who are thinking - 'but Microsoft says that their office file formats are now XML based'. To you all I can say is that you should learn XML, and then you'll realise that what Microsoft is doing doesn't really have anything to do with what XML is all about).
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.
You may want to take a look at XML Spy as an XML Editor. It's a commercial product (about $199), but I've used it to build a DocBook file, and then used the DocBook XSLT scripts to generate HTML. I've also used it to generate custom DTDs, which worked pretty well. The product can import Word files (converts Word Styles to element types). What they really need is an XSL script to generate Word formatted files. That would be great! I'm not sure your basic office folks are quite ready for it, but with a little training, they might be weaned off of Word.