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."
Keep including excerpts/relevant portions in the documentation, and separately, provide supporting reference materials - full XML files, XSD, etc.
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
You do good XML documentation the way you do good documentation of any kind...
1) Examples.
2) Functional examples.
3) More examples.
People learn best when they have a skeleton of knowledge to hang the meaty details on. By all means, have a detailed description of each element in the XML, but give lots of examples so people can get a sense of the big picture of what's going on. And make sure your example are real-world enough to cut/paste and modify for people who need to get something up and running in a hurry.
There's a reason that K&R is considered one of the best language books every written. It has tons of examples, and also has a lot of the formal stuff in a useful format.
Sometimes it's best to just let stupid people be stupid.
For those of us actually interested in opinions / answers to the poster's question, please actually respond to the QUESTION. Anonymous didn't ask for criticism over the choice of languages, keep that in mind.