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."

Comments

Supporting materials

[beavis88]

Keep including excerpts/relevant portions in the documentation, and separately, provide supporting reference materials - full XML files, XSD, etc.

Word is the wrong tool

[Anonymous Coward]

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.

Complementing

[Nosklo]

You may try StylusStudio's xml schema documentation generator or simpler/opensource/customizable dtdtoc written in python.

Use 'raw' XML examples *too*.

[mrjb]

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.

JSON

[texwtf]

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.

I always let...

[mdm-adph]

...XML document itself. :P

(Isn't that the beauty of it?)

Documenting XML?

[DogDude]

I thought that the point of XML was to embed the documentation in with the data, so that it was human-readable? This doesn't make any sense. If XML has to be documented anyway, then what's the point? To increase network traffic? To fill up "extra" hard drive space? Old fashioned character-delimited is a better way to go if you have to document the thing, anyway.

Re:Documenting XML?

[beavis88]

I thought that the point of XML was to embed the documentation in with the data, so that it was human-readable?

This is definitely not the point of XML. The point is generic exchange of structured data, with the ability to validate and query the data.

You could certainly argue it hasn't lived up to those aims, but that's a different argument in my book...

Cut and Paste from Visual Studio

[HappyUserPerson]

If you need to have XML fragments in your Word document, one of your best options is to copy and paste from Visual Studio. The result is nicely indented, colorized and mono typed. If you don't have Visual Studio, you can download it Visual Studio Express for free.

Just open Visual Studio and create a new XML file (don't create a project-- there's no need to do so; just use File->New->File... and select XML file). Copy and paste your XML fragment into the new file. Press Ctrl-K, Ctrl-D to reformat the document. Then just select the fragment you want and copy and paste into Word.

I hope that helps.

Good XML Documentation

[Reality Master 101]

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.

There is a time tested solution: DocBook

[badger.foo]

If you're already dealing with XML files, I would suggest that the main barrier to using a toolset such as DocBook (SGML or XML variants) should be gone already.

DocBook is excellent at enforcing proper structure and contains all the elements you need (really!) to write tech documentation.

Several high profile projects such as FreeBSD, KDE, GNOME and others use DocBook as their main doc format, as do I believe more tech companies than actually want to admit it. I maintain the PF tutorial at http://home.nuug.no/~peter/pf/ as DocBook SGML myself.

The tools most people use for DocBook are free (most likely just a few mouse clicks or commands away through your package system), but some proprietary/commercial tools are available too. The main reference is at docbook.org, it certainly would not hurt to check it out.

Tibco TurboXML DTD Diagrams

[Cheefachi]

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!

Right Tool: YAML

[goombah99]

If I understand the question right, how to present structured documents within human readable text then closest you will ever come to a right answer is YAML. look it up at wiki pedia.

link

[goombah99]

oops, Here's the link. Also a word of advice: you can embed XML without modification in YAML just by indenting it. So you can have both in the same document. Unlike XML, YAML allows for some (limited) relational hierarchy and for type casting as part of the language itself. You can use this to simplify a highly nested XML document with lots of redundant entries. just make an !!xml type-def.

Slightly off-topic, but...

[Mortanius]

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.

Use Word styles

[Mean Variance]

This is what I did. Create a new style based on predefined style HTML Preformatted. Name it XML Sample. Make sure "Style for following paragraph" is also XML Sample. I use a 15% Gray background pattern and Courier New 10pt and a 0.3" indent to set it off.

For better or worse, where I work, tech specs are Word. I use the style just mentioned for my XML or sometimes embed XML Spy schema fragments as JPEG.

Re:this should work for you:

[dvice_null]

That is pretty good, but as your example is not valid XML, we need to wrap it inside a valid XML to make it actually work:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE documentation [
<!ELEMENT documentation (#PCDATA)>
]>
<documentation>
<![CDATA[<XML documentation>XML documentation</XML documentation>]]>
</documentation>

Use XML

[frisket]

If you're serious about doing documentation, use an XML editor with something like the DocBook DTD/Schema, not Word. Word is for shopping lists and letters, not "real" documentation. And yes, Word does actually have a real XML editor, but it's pretty crummy; and no, Save As XML (WordML or OOXML) doesn't count.

The problem is that most XML document editors suck for non-XML-gurus. They can display either plaintext with syntax colorisation (Emacs/psgml/xxml) or pseudo-WYSIWYG, but lack the interface smarts that would make them usable (see my paper to Markup last year on this topic, or wait for the full report next year :-). Both have their advantages and disadvantages but they all require a fairly deep prior knowledge of XML. In your own case this may be fine, but not if you want to hand the editing suite to your non-XML colleagues.

A good documentation system takes some effort to build, but the results in terms of usability, persistence, quality, etc are usually well worth it. In the specific case of quoting code, XML's CDATA section feature lets you embed code verbatim, and one of the possible outputs is to transform the XML to LaTeX using XSLT, and thus enable the use of things like the listings package, which makes pretty-printed code in your PDFs.

Choose a good schema language

[srussell]

If you're using XMLSchema, then ditch that crap and use RelaxNG, which is actually readable. There's a compact syntax that is even more user-friendly. As an example, the schema for:

<addressBook>
<card>
<name>John Smith</name>
<email>js@example.com</email>
</card>
<card>
<name>Fred Bloggs</name>
<email>fb@example.net</email>
</card>
</addressBook>

looks like this:

element addressBook {
element card {
element name { text },
element email { text }
}*
}

Use your imagination to pretend that /. preserves indentation. --- SER

This Works For Me

[ToxicBanjo]

Like most coders I've been having to do this for some time. My approach seems to allow our customers to easily understand the XML we use:

1. Data Requirements (DB Schema and Expected Values/Ranges)
2. Sample XML Without Data, Just the Schema Values From (1). ie. [FirstName]nVarChar(15)[/FirstName]
3. Then Show the XSD File That Validates the XML.

Then a full description of each element, etc followed by some samples. True this can get lengthy for really complex schemas but even then it makes it pretty easy to read and "understand" WTF is going on.

Just my $.02