Slashdot Log In
Embedding XML In Docs?
Posted by
kdawson
on Tue Sep 25, 2007 12:53 PM
from the techniques-and-tips dept.
from the techniques-and-tips dept.
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."
Related Stories
Submission: Embedding XML in docs by Anonymous Coward
This discussion has been archived.
No new comments can be posted.
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
Supporting materials (Score:4, Insightful)
XSLT Documentor (Score:2)
So it's your choice, you have complete documentation, or you can get documentation on any call by passing its content through the XSLT.
Re: (Score:2)
It's basically a series of <xsl:template match="functionname"> or <xsl:template match="functionname[conditional='foo']">, with markup to describe the purpose, arguments, etc of the functions. The "all documentation" XML file is a table of contents and series of dummy calls or responses which the individual documenting xsl:templates then mark up.
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.
Right Tool: YAML (Score:3, Interesting)
link (Score:3, Interesting)
Re: (Score:2)
Re: (Score:2)
Word is perfectly capable of accepting XML input. 2 of the 8 docs I've been working on this month have XML in them. It works out just fine.
Re: (Score:2)
Use 'raw' XML examples *too*. (Score:5, Insightful)
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.
Re: (Score:2)
Perhaps, but it bears repeating that in most cases, man pages can be considered both authoritative and complete. Compare that with what you typically get with commerical vendor-supplied documentation. I'll agree that for casual use, reading a manpage can be overwhelming, but so is reading a manual of any sort. The more features there are, the more there is to rea
Re: (Score:2)
As for your ping example, I don't know what version you're using, but typically the manpage would take the form of:
ping [option] [option] [option] [option] host
Mine's even worse than the grandparent's:
SYNOPSIS
ping [-AaDdfnoQqRrv] [-c count] [-i wait] [-l preload] [-M mask | time]
[-m ttl] [-P policy] [-p pattern] [-S src_addr] [-s packetsize]
[-t timeout] [-z tos] host
ping [-AaDdfLnoQqRrv] [-c count] [-I iface] [-i wait] [-l preload]
Re: (Score:2)
SYNOPSIS
ping [-LRUbdfnqrvVaAB] [-c count] [-i interval] [-l preload] [-p pattern]
[-s packetsize] [-t ttl] [-w deadline] [-F flowlabel] [-I interface] [-M hint]
[-Q tos] [-S sndbuf] [-T timestamp option] [-W timeout] [hop
The granparent should be pleased, his manpage is actually the most readable.
What Are the Rest of us Doing? (Score:2)
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.
I always let... (Score:5, Funny)
(Isn't that the beauty of it?)
Re: (Score:2)
>
> (Isn't that the beauty of it?)
<SENTENCE>Because if <SUBJECT>it</SUBJECT> <PREDICATE>was impossible</PREDICATE> for a <OBJECT>human</OBJECT> to generate, <SUBJECT>it</SUBJECT> <PREDICATE>should be impossible</PREDICATE> for a <OBJECT>human</OBJECT> to understand!</SENTENCE>
Re: (Score:2)
You remind me of the cardinal tenet of XML:
Re: (Score:2)
Re: (Score:2)
Unfortunately, I suffer from a colleage who favours single letter tag and attribute names
Oh, and I use Natural Docs to create documentation and use (start code)
Documenting XML? (Score:3, Interesting)
Re: (Score:3, Informative)
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...
Re: (Score:2)
Knuth has written a few things about why this style of parsing is bad (he used it in TeX) and why it should be avoided for anything but interactive stuff. If you do the proofs, you will see that XML errors diverge to two states, one takes an infinite amount of time and the other an infinite amount of memory.
Re: (Score:2)
Re: (Score:2)
Cut and Paste from Visual Studio (Score:2, Informative)
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
Good XML Documentation (Score:4, Insightful)
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.
XSD (Score:2)
Throw comments into the XSD, and it's gold.
Re: (Score:2)
Re: (Score:2)
Right. And what about capturing mechanisms? For example if you had to take the value from one part of the XML...
That's where notation systems such as http://www.bpmn.org/ [bpmn.org] or http://www.oasis-open.org/committees/wsbpel [oasis-open.org] might be useful.
There is a time tested solution: DocBook (Score:2, Informative)
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.n [home.nuug.no]
Tibco TurboXML DTD Diagrams (Score:4, Informative)
Slightly off-topic, but... (Score:3, Insightful)
Use Word styles (Score:2, Informative)
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 (Score:3, Informative)
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.
Re: (Score:2)
Sorry, just had to stop you there. If you're serious about doing anything - don't touch XML. It's shit, it was designed by idiots and it achieves nothing. Just don't go there. Use TeX or Word or a fucking crayon.
The reason XML editors suck is that XML is hopeless for human editing. It is too complex, to losely defined (ie, it's TOO general) and even reading it is a pain, let alone writing it.
Stamp out XML at every opportunity; like cockroch
Re: (Score:2)
I have to ask. How many years have you made a living writing "real" documentation? Because I really, seriously get the impression that your idea of doc is "commenting my code for college credit".
Word is just right (Score:2)
Pay no attention to the neanderthalers who want you to regress to some text processing application.
Word is ideal for tech documentation, as it gives you the tools to do better-than-good typography, as well as to easily enhance the text with illustrations and inclusions—to create documentation that's tuned for the reader, not the writer.
I'm assuming you know how to set up suitable styles. For the rest, you have more than cut and paste as an option. Keep in mind that you can embed just about any file
Word is just right for replacement (Score:2)
1997 called and wants it's analysis of Word back. In '97 Word was the best solution. I wrote professional level technical documentation for distribution to clients using Word 97, and it is was best of breed. Flash forward to 2007. There is a tool called Open Office
Re: (Score:2)
Now read the rest of what I posted.
Ever heard of DocBook? (Score:2)
I don't even understand the question (Score:2)
Actually DELIVERING something, apart from polemic (Score:2)
As for tools - one works with what one has/c
Choose a good schema language (Score:4, Informative)
Describe the objects (Score:2)
Re: (Score:2)
try to preserve XML color of your editor (Score:2)
Export the xml file to html and then copy/paste from ie to word. "xml now in real color!"
but you just do that in the overview documents, you also need to provide a real reference and not just a DTD you need to provide detailed appendix style document in human readable form.
heres' what I do (Score:2)
XML Sample files
Store sample documents in a \Samples subdirectory under the directory storing the word files. The word document must 'include' them by using the "Insert\File\Insert as Link" functionality in MS word.
XML Structure tables
The most useful way to illustrate XML visually doing the following:
1. Take an XML document that illustrates as much of the schema as possible.
For instance, this could be a document that includes all optional elements. (This may not be possible in some ca
Complementing (Score:5, Interesting)
Parent
Re:this should work for you: (Score:4, Funny)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE documentation [
<!ELEMENT documentation (#PCDATA)>
]>
<documentation>
<![CDATA[<XML documentation>XML documentation</XML documentation>]]>
</documentation>
Parent