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

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 [microsoft.com] 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.

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/ [home.nuug.no] 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!

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.

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 [epu.ucc.ie] 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 [relaxng.org], which is actually readable. There's a compact syntax [relaxng.org] that is even more user-friendly. As an example, the schema for:

<addressBook>
<card>
<name>John Smith</name>
<email>[e-mail]</email>
</card>
<card>
<name>Fred Bloggs</name>
<email>[e-mail]</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