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?"
Standards are good. XML is good. Documentation should be in a standard format. Network traffic should be in a standard format. IPC traffic should be in a standard format. XML is good.
.
Developers,Developers,Developers,Developers....
-teknopurge
http://techienews.utropicmedia.com help us beta!!!
Website Hosting
Document interchange with our customers had to be in WOrd, so thats what we got stuck with eventhough we initially started off in the direction you are heading.
Good luck taking on the Microsoft Monster.
Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo! http://goo.gl/J9bkO
It sounds to me like you're already a step ahead of the rest of the world, for the most part.
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. No open, standard, consistent tools to examine all of our documentation. Yeah, you can grep HTML, but the others are a pain. And don't even think about automatic script language based conversion among these formats.
I suspect you're more advanced in your thinking than 90% of the places out there. Why not continue with your thinking and let the rest of us know what you decide?
"Provided by the management for your protection."
1) Your point is irrelevant since this discussion is not about HTML.
2) XML is not a replacement or a complement for HTML. HTML has nothing to do with XML. XML is a extensible markup language which can be used to transfer an infinitum of data forms, HTML happens to be one of th emany many uses it has, but not nearly the most important. XML is more commonly used for databases, RPC calls, log files, EDI, or new languages than as a complement for HTML.
Forget about how do you build the repository -- that's easy. (Well, okay, non-trivial, but with databases, cvs, and even just simple shared folders, storing the docs is the least of your worries).
:) ) But again, the long pole of the tent was the editor widget.
I still maintain that the biggest hurdle in any standardized document system (especially if you include multiple concurrent authors) is the front-end editor. I wrote a simple (and highly buggy, I'll admidt, so you who know me keep your traps shut!) VB application that provided a multi-user front end to a database. The back-end (PHP) pulled all the appropriate rows for any given doc together and mashed it into a nice, navigable HTML document. I even had PDF support at one time (but it was even flakier than the GUI).
However, it was not XML, so it was REALLY limited in how easy it was to create new views on the data. The biggest problem I ran into was trying to find a good GUI editor -- this thing was written for security engineers, not HTML experts, and I wanted them to concentrate on content, not tags. I eventually settled (and settled is the right word) on the Microsoft DHTML control. Worked well enough for the time (two years ago at this point), but I still think half my problems stemmed from that widget, or bad interface programming to it. The advantage? WYSIWYG (more or less) editing. Seamless multi-user editing of the same document (well, okay, we had some record locking issues.
Since then, I've wanted very much to rewrite the thing to handle full XML, and I understand there's an effort underway to do just that (I've since moved to different pastures), but it's slow going. I've looked at current technology (ABIword, for example), and i'm just not convinced that it's going to be easy to get a good semi-WYSIWYG XML editor going. At least not on the cheap.
Some time ago was posted here an app called Conglomorate, which I still think has about the best approach to visually representing an XML document. But it hasn't been updated in forever, and was slow/buggy the one time I played with it. More recently, the XMLmind XML Editor (XXE) has shown a lot of promise, even including CSS files for editing DocBook XML. They even have source available. Again, goes a long way to letting you edit diverse XML files in a logical way -- not by forcing you to look at ugly tree-views of an XML file, like so many first-generation editors. Finally, the latest XML Spy editor beta goes a bit father even than XXE, using a full XSLT transform to provide a WYSIWYG format for XML files. Theoretically, with this, you should be able to display any of your documents in whichever approach you like -- full WYSIWYG, tables, trees, block labels, whatever.
Of course, neither of these latter tools work in a concurrent editing fashion. But that's a "minor" enhancement -- put together a robust DB back end, allow for good record locking, editor-to-editor communications for lock management, transaction log to allow back-out of changes, etc. Lots of possibilities. Take XXE, put this kind of capability on the back-end, an integrated login and document management system, and you've got a kick-ass document solution. Work the backend to allow for multi-stage review and publishing, and provide output engines for HTML, PDF, WAP, whatever, serve different subtrees of the system to, say, internal project web servers, external web servers, sales and marketing (for glossies), etc., and everyone can manage everything, real-time, GUI, with one tool.
But I dream.
(seriously -- if anyone's really working this, I'd love to help. I just wanna use it at home for my own web pages.)
More exactly one of the best incarnation I know of : twiki (twiki.org). Absolutly terrific ! it can be used as a collaboration medium, a knowledge base repository and much, much more, you will find new ways of using it everyday. I have installed it where I work ! and people have been ecstatic !
You just proved his point. Displaying XML as HTML is the only way to insure compatibility cross browsers. XSLT, DOM parsing, and SAX parsing use transformations into HTML to display the XML. You notice you are still using HTML? I do!!! It's not the direct use of HTML to style the XML, but it is still HTML. XSLT's template formatting is based on HTML you know. Since, the majority of web browsers only read HTML directly HTML is the easiest and most logical way to style XML. By that definition, XML is a complement to HTML because HTML will still exist regardless. With that said, if we ditch HTML what are we going to use to style the XML? What would the web browser developers have to create to style XML in the browser? They'd have to integrate an XML based schema for styles...hey that's what XHTML/HTML is!!! XHTML is just an XML representation of HTML in insure your style and outputs are valid and well formed. And yes, I know you can use CSS to style XML but that is not totally cross browser. We still have those people running around with Netscape 4 out there that doesn't support any of this stuff. It's silly to say HTML is dead.
True enough, but it doesn't answer the original question. Can MS-Word (or even StarOffice, if you want a non-MS option) output XML? I know it will output HTML, but it's such a bastardized mass of proprietary and font/format specific crap that it's essentially useless unless you extensive filter it first.
The whole point here is not to create pretty formatted documents, but to leverage the power of XML to add context and meaning to the content of the documents in order to create a rich and interlinked heirarchy of information. Conventional word processors just create blobs of information -- pretty formatted blobs, but blobs nonetheless...
Your Servant, B. Baggins
I just finished using docbook-xml 4.1.2 - docbook-dsssl 1.71(contains a print and an HTML sytlesheet for use with RTF and TeX backends) - openjade 1.4devel1 (which uses the stylesheets just mentioned in its RTF and TeX backends) and pdfjadetex to produce a 140 page technical manual in .pdf format. I used psgml mode with Emacs 20.7 as my editor. (I was looking at the interesting group of programs called psgmlx but didn't have time to actually try them.)
.pdf.
In short, for editing, Emacs/psgml mode worked fine, but the complexity of keyboard commands, my aging brain, and deadline pressure meant that I could only learn to use a small chunk of the possible features, especially of psgml mode which, unlike Emacs, was new to me. I opened one Emacs frame on one page on a 4 x 7 desktop for each chapter and then skipped from desktop page to desktop page with a full screen for each. Hint: Make a tags table so that you can then do search and replace operations across all files that make up your book. (See 22.16 Tags Tables in the latest GNU Emacs Manual (14th edition).)
Using docbook-xml, I found that tables were difficult, too difficult. I was unable to make a simple 3 colum x 5 row table within the hour I'd alloted and finally gave up. Ended up using the tag to get literal text. Fortunately, only one or two tables were desired. Checking the archives on the docbook-related mailing lists, I was not able to put Norm Walsh's advice (given to someone with a similar table-related problem) to go read the info on the new table model to practical use within my limited timeframe.
Also, index generation was a bitch. I used collateindex.pl in conjunction with openjade. There must be a better way, but I couldn't find it in the limited time I had.
No graphics were included, but some of the traffic regarding the problems of others gave me a headsup that I should allow plenty of time for experimentation before actual work could begin, learning how to insert both vector and bitmap graphic files in a document that would be turned into a
Incidently, I was also able to produce MIF files for FrameMaker from the same XML source with openjade, a client requirement.
YMMV.