Embedding XML In Docs? 90
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."
Word is the wrong tool (Score:5, Interesting)
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 (Score:5, Interesting)
JSON (Score:4, Interesting)
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.
Documenting XML? (Score:3, Interesting)
Right Tool: YAML (Score:3, Interesting)
Re:Supporting materials (Score:1, Interesting)
And then it uses an XPath-like syntax to point elements and attributes out and describe them, as in:
It's a very readable way to document and even people who normally only read examples have no problem parsing this. Smart developers on the receiving side code to this and don't bother with the XSD. People who are slaved to their XSD to Java tools have to use the XSD and end up in a world of pain.
link (Score:3, Interesting)