Slashdot Mirror
Embedding XML In Docs?
An anonymous reader writes "Now that XML is the de facto standard (for good or ill) for doing message passing, I find that I need to give XML examples in the documentation that we produce. We're stuck with Word and up till now I've just been doing the examples as cut and paste from the log files. We include schemas in the appendix but it seems that the clients like the 'readability' of the raw XML over other approaches we've tried. I'm wondering what everyone else is doing in the world of XML documentation."
Asking how to do this in Word is like asking how to cut a board in half with a hammer. In both cases, you're using the wrong tool for the job.
That said, I can tell you what we do for documentation. We have a wiki (Confluence, though any should work) that is perfectly capable of handling XML or any of a number of languages. We then have automated processes which periodically pull certain pages, strip the navigation elements and render them to PDF which, depending on the process, get transfered to various locations (samba fileshare, a couple of different intranet sites we maintain or into our CMS workflow to be approved and added to our public site).
Since it's a wiki, the input is easy and anyone in our company can contribute (if we were larger, we might add more access controls). Yet it also produces professional-looking PDF documents.
You may try StylusStudio's xml schema documentation generator or simpler/opensource/customizable dtdtoc written in python.
find -name "*base*" -exec chown us {} \; ; ln -s
No trolling intended, but just having the schemas is like just having the UNIX man pages without examples.
...
Let me clarify, bear with me- The man page for 'ping', for instance, is all-encompassing but rather intimidating when it comes to every-day use:
NAME
ping - send ICMP ECHO_REQUEST packets to network hosts
SYNOPSIS
ping [-dfnqrvR] [-c count] [-i wait] [-l preload] [-p pattern]
[-s packetsize]
DESCRIPTION
Ping uses the ICM... etc
Okay, enough. At that point, they've more than lost me. All I want to know is, How do I use it?
A simple example gives much more 'instant gratification' style information:
user@host:~$ ping www.google.com
PING www.l.google.com (64.233.183.104) 56(84) bytes of data.
64 bytes from nf-in-f104.google.com (64.233.183.104): icmp_seq=1 ttl=245 time=11.3 ms
64 bytes from nf-in-f104.google.com (64.233.183.104): icmp_seq=2 ttl=245 time=69.3 ms
This is enough for everyday use. No need to bother with the gritty details at first. Once the users get to that point, they won't mind the schemas and full help descriptions.
Visit http://ringbreak.dnd.utwente.nl/~mrjb/growingbettersoftware to download your free copy of the book
Before you flog yourself too much with XML, check out JSON: http://www.json.org/.
It's supported by every language under the sun, and really simple to use. You may end up needing the extra capabilities of XML, but if you don't JSON is a much friendlier experience.
...XML document itself. :P
(Isn't that the beauty of it?)
It is by my will alone my thoughts acquire motion; it is by the juice of the coffee bean that the thoughts acquire speed
We publish tons of documentation that has to explain XML formats. What we do is include DTD diagrams in our documentation that shows the structure of the XML document graphically. The tool we use to generate them is Tibco's TurboXML and we've been using it for years. Obviously we include examples, but the DTD diagrams really show you all you need to know. I know, I know its commercial software. Maybe there's something open source out there that does something similar, not sure. Hope this helps!
An engineer is someone who spends 3 hours trying to solve a 2 hour problem in 1 hour - Anonymous