Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Embedding XML In Docs?

kdawson posted more than 6 years ago | from the techniques-and-tips dept.

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

Sorry! There are no comments related to the filter you selected.

Supporting materials (3, Insightful)

beavis88 (25983) | more than 6 years ago | (#20746205)

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

Re:Supporting materials (1)

jdeisenberg (37914) | more than 6 years ago | (#20746513)

Yes, I agree. Here are a couple of examples, one is from lecture notes for an XML class: http://evc-cit.info/cit041x/lecture8.html [evc-cit.info] , the other is a book about OpenDocument Format: http://books.evc-cit.info/odbook/book.html [evc-cit.info] , which includes lots of examples. Obviously, the same formatting and presentation could be used in a Word document.

Re:Supporting materials (1, Interesting)

Anonymous Coward | more than 6 years ago | (#20747277)

The SOAP/XML specifications in the WS-* family of specs use something people often call "pseudo-schema". Look at WS-Eventing [w3.org] for example. Section 2.1 describes this notational convention. And here is an example of how it is used to describe the "subscribe" SOAP message defined by the spec (section 3.1):

<s:Envelope ...>
    <s:Header ...>
        <wsa:Action>
            http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe [xmlsoap.org]
        </wsa:Action> ...
    </s:Header>
    <s:Body ...>
        <wse:Subscribe ...>
            <wse:EndTo>endpoint-reference</wse:EndTo> ?
            <wse:Delivery Mode="xs:anyURI"? >xs:any</wse:Delivery>
            <wse:Expires>[xs:dateTime | xs:duration]</wse:Expires> ?
            <wse:Filter Dialect="xs:anyURI"? > xs:any </wse:Filter> ? ...
        </wse:Subscribe>
    </s:Body>
</s:Envelope>

And then it uses an XPath-like syntax to point elements and attributes out and describe them, as in:

/s:Envelope/s:Header/wsa:Action
    If a SOAP Action URI is used in the binding for SOAP, the value indicated herein MUST be used for that URI.

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.

XSLT Documentor (1)

nahdude812 (88157) | more than 6 years ago | (#20747481)

We use a large XSLT file (more accurately a series of files with xsl:includes) which document the functions of the XML. You can transform any XML query or response with this XSL, and it will document the call for you. There's also an XML file which when transformed with this XSL will give you full schema documentation.

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:XSLT Documentor (1)

hummassa (157160) | about 7 years ago | (#20756303)

Linky, linky, please???

Re:XSLT Documentor (1)

nahdude812 (88157) | about 7 years ago | (#20762631)

Sorry, it's for internal applications shared between teams, I don't have a public link to it.

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.

XML (0)

Anonymous Coward | more than 6 years ago | (#20746265)

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

Jabber basically is an XML bridge. Combined with Peer to Peer [amazon.com] it's a powerful combination.

Word is the wrong tool (5, Interesting)

Anonymous Coward | more than 6 years ago | (#20746271)

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.

Right Tool: YAML (2, Interesting)

goombah99 (560566) | more than 6 years ago | (#20747151)

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 (2, Interesting)

goombah99 (560566) | more than 6 years ago | (#20747461)

oops, Here's the link [wikipedia.org] . 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.

Re:Word is the wrong tool (1)

yetanothertechie (699283) | more than 6 years ago | (#20747189)

We then have automated processes which periodically pull certain pages, strip the navigation elements and render them to PDF

The importance of keeping your distributed docs up to date, as described above, deserves emphasis. It's highly frustrating try to program to an API with an old version of the documentation.

I also agree that Word is a lousy way to produce this type of documentation. I would go further and say that it is a poor tool to use for most non-static technical documentation. It's update capabilities seem well-suited to more narrative documents but are cumbersome and confusing for technical documents.

Re:Word is the wrong tool (1)

cbiltcliffe (186293) | about 7 years ago | (#20751331)

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.
No...you're just not hitting it hard enough.....

Re:Word is the wrong tool (1)

cprael (215426) | about 7 years ago | (#20751977)

One works with the tools one has available. The startup I'm writing docs for right now works in Word (Office 03, actually). The previous one used Frame, because they actually had _had_ a full-time writer before I came on board.

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:Word is the wrong tool (1)

Xiaran (836924) | about 7 years ago | (#20753413)

While I agree with you 100% I must say Ive been in business environments where they *insist* that it be word format. No PDF. No HTML. And if you get caught using something like *gasp* open office you get reprimanded. Sad but true.

Word? Try HTML. (1)

Nosklo (815041) | more than 6 years ago | (#20746277)

We're stuck with Word
Word file is the worst way to document xml ever. Try a hyperlinked help file or plain html, much easier to do something neat.

this should work for you: (-1, Redundant)

circletimessquare (444983) | more than 6 years ago | (#20746297)


XML documentation

i keed, i keed

this should work for you: (0)

circletimessquare (444983) | more than 6 years ago | (#20746325)

<XML documentation>
 
XML documentation
 
</XML documentation>
i keed, i keed

Re:this should work for you: (0)

Anonymous Coward | more than 6 years ago | (#20746555)

-1, Go Back to K5.

Re:this should work for you: (3, Funny)

dvice_null (981029) | more than 6 years ago | (#20749053)

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 'raw' XML examples *too*. (5, Insightful)

mrjb (547783) | more than 6 years ago | (#20746327)

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.

Re:Use 'raw' XML examples *too*. (1)

value_added (719364) | more than 6 years ago | (#20748017)

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:

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 read, and the more there is to learn. That benefits of standardisation exist, but become apparent only after you start reading.

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

Even a novice or casual user should be able to determine that the stuff surrounded by square backets, no matter how numerous, are options (and are therefore, "optional"), and quickly conclude that the most basic usage is quite simply:

ping host

Wasn't so hard, was it? On the other hand, you may luck out on occasion and discover the "shortcut" you're looking for, but the underlying truth to "If all else fails, read the instructions." remains, and no amount of "La la la I can't hear you." won't convert a false economy into a real one.

Granted, certain manpages could use more "examples", but that's little different than saying "The documentation could be improved." I think that's true in all cases, and I doubt there's a documentation writer anywhere who would disagree with you. In any event, you could make use of (or suffer through, depending on your preferences) the info pages which are typically written to provide extensive example usage. Or, alternatively, write your own and put them in ~/man.

Re:Use 'raw' XML examples *too*. (1)

sarahbau (692647) | about 7 years ago | (#20750629)

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]
                    [-M mask | time] [-m ttl] [-P policy] [-p pattern] [-S src_addr]
                    [-s packetsize] [-T ttl] [-t timeout] [-z tos] mcast-group

This is in OS X

Re:Use 'raw' XML examples *too*. (1)

josephdrivein (924831) | about 7 years ago | (#20752793)

From Debian:

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 ...] destination

The granparent should be pleased, his manpage is actually the most readable.

Re:Use 'raw' XML examples *too*. (1)

jhol13 (1087781) | about 7 years ago | (#20752369)

Completely off topic, but see http://docs.sun.com/app/docs/doc/816-5166/ping-1m?a=view [sun.com] .

This is why I use Sun manual pages (even though they miss GNU extensions and are sometimes very slow).

What Are the Rest of us Doing? (1)

segedunum (883035) | more than 6 years ago | (#20746337)

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.
Having as little to do with it as possible. Everybody just grabs any raw XML they can find in order to try and understand it, and they fly by the seat of their pants. Not much you can say will change that.

Re:What Are the Rest of us Doing? (0)

Anonymous Coward | more than 6 years ago | (#20747839)

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.
Having as little to do with it as possible. Everybody just grabs any raw XML they can find in order to try and understand it, and they fly by the seat of their pants. Not much you can say will change that.
And that's a good thing is it? In my experience an amazingly high proportion of developers don't do any code documentation at all unless they are forced to do it. This is a major reason why a lot of time is wasted the moment a new developer joins a team since it takes him significantly more time to plow his way through a whole pile of undocumented code than it would if take if the original developer had made even a half hearted attempt at commenting his code. Its pretty sad that there are developers out there who are only vaguely aware of what javadoc [sun.com] is and when pressed don't even know how to use it. The same can be said about many other common development tools. I've actually met developers who don't know how to use Make or Ant. Committing your <insert name of your favorite IDE> projects directly into CVS/Subversion is only a good idea until you have to cooperate with a team using a different IDE, with Ant you get complete IDE independence.

this is so scary... (1)

kenjishikida (324233) | more than 6 years ago | (#20746383)

I really don't know if this is a good idea

JSON (4, Interesting)

texwtf (558874) | more than 6 years ago | (#20746397)

Before you flog yourself too much with XML, check out JSON: http://www.json.org/ [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.

Re:JSON (1)

texwtf (558874) | more than 6 years ago | (#20746415)

..well, it's good for message passing anyway. It may not be what you want for embedding documentation. Sorry for the late clarification.

I always let... (5, Funny)

mdm-adph (1030332) | more than 6 years ago | (#20746403)

...XML document itself. :P

(Isn't that the beauty of it?)

Re:I always let... (1)

Tackhead (54550) | more than 6 years ago | (#20746577)

> I always let... ...XML document itself. :P
>
> (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>

ahem... (1)

LiquidCoooled (634315) | more than 6 years ago | (#20746727)

Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

Not everything is instantly understandable.

For help on the sentence, see wikipedia [wikipedia.org] .

Re:I always let... (0)

Anonymous Coward | more than 6 years ago | (#20747077)

Uhh, not that you weren't joking, but you can't/shouldn't have multiple values in a tag.

Your xml sentence is: Because if for a to generate for a to understand.
With child elements subject, subject, predicate, predicate, object, object (that don't neccesarily maintain order!).

Since I'm posting AC, I'll just be terse: Your schema sucks.

Re:I always let... (1)

idontgno (624372) | more than 6 years ago | (#20748347)

You remind me of the cardinal tenet of XML:

XML is like violence. If it's not solving your problem, you're not using enough of it.

Re:I always let... (1)

dossen (306388) | about 7 years ago | (#20753475)

Or as one of my coworkers just said: "XML is like alcohol, use enough and you can't see the problem".

Re:I always let... (1)

ErroneousBee (611028) | more than 6 years ago | (#20749335)

If you choose the tagnames wisely, this can be true.

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) ... (end code) to document the XML within inches of the place where the XML is generated or parsed.

Documenting XML? (2, Interesting)

DogDude (805747) | more than 6 years ago | (#20746417)

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? (2, Informative)

beavis88 (25983) | more than 6 years ago | (#20746505)

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

Re:Documenting XML? (1)

BlowHole666 (1152399) | more than 6 years ago | (#20746567)

This may help you out

It started as a simplified subset of the Standard Generalized Markup Language (SGML), and is designed to be relatively human-legible.
http://en.wikipedia.org/wiki/XML/ [wikipedia.org]

Re:Documenting XML? (1)

poopdeville (841677) | more than 6 years ago | (#20746917)

Which doesn't contradict the GP. XML is an easy to parse and validate fragment of SGML. It is also slightly easier for a human to read.

Indeed, I just rephrased your quotation.

Re:Documenting XML? (1)

thogard (43403) | about 7 years ago | (#20750905)

If its so easy to parse, why are the libraries that parse it such a pain to use? Also why do they burn memory like crazy as well?
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:Documenting XML? (1)

laptop006 (37721) | about 7 years ago | (#20754223)

And both take an infinite amount of money.

Re:Documenting XML? (0)

Anonymous Coward | about 7 years ago | (#20769643)

If its so easy to parse, why are the libraries that parse it such a pain to use?

I'm not sure which you're talking about here. I presume it is because you're either looking at a document with a painful structure, or are doing non-trivial transformations on one.

Also why do they burn memory like crazy as well?

Because they return a large number of complicated objects? Each attribute or subelement is presumably going to get its own accessor/object.

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.

I strongly doubt Knuth would have used the word 'infinite' in such a sloppy manner. And with all due respect to him, who cares? XML documents do not have unbounded length in practice.

Come to think of it, I think your paraphrase of Knuth's results are incorrect. It's obvious that errors requiring unbounded memory to notice are going to require unbounded time as well. (Otherwise, when and how is that memory going to get filled?) And vice-versa.

Re:Documenting XML? (1)

Doctor Memory (6336) | about 7 years ago | (#20790421)

If its so easy to parse, why are the libraries that parse it such a pain to use?
Probably because, as someone else pointed out already, XMl is intended to express structured data. Therefore, it's best to have some idea what the structure is before you start parsing it. Sure, you can just grab a stream and start pulling tags out of it, but then you have to keep track of what tag you're working with, make sure things are well-formed and a bunch of other stuff that gets in the way of just grabbing the data you went in for in the first place.

OTOH, if you've got the schema for the XMl you're parsing, then you can use something like JAXB to generate a bunch of classes that represent all the elements, then just create an Unmarshaller, pass it your XML, and it passes you back a reference to the class that represents the root element and you can traverse it, grab the data, frob the figures, then create a Marshaller and hand it the root element and have it spit out a new XML document. Painless & brainless, and works really well for things like web services that publish their schemas.

I'm not sure what the memory usage is, I certainly wouldn't bet that it's negligible, but it's probably not outrageous, either. Predictable is often just as good as efficient, since at least you know what to expect.

Re:Documenting XML? (1)

smellotron (1039250) | about 7 years ago | (#20751039)

XML is an easy to parse and validate fragment of SGML

XML and SGML are not interchangeable. <foo/> is a self-closing tag in XML. <foo/ is a self-closing tag in SGML (full SGML really has weird syntax to anyone used to HTML or XML). XML is easier to parse than SGML, specifically because it is not SGML.

Re:Documenting XML? (1)

poopdeville (841677) | about 7 years ago | (#20769367)

You are right.

Re:Documenting XML? (1)

iabervon (1971) | more than 6 years ago | (#20747347)

It's so that intermediary software can manipulate the files without knowing anything about the semantics. For example, jabber makes good use of it so that clients can support a variety of extensions while services only need to handle a single function while letting messages with additional contents pass through intact.

Cut and Paste from Visual Studio (4, Informative)

HappyUserPerson (954699) | more than 6 years ago | (#20746509)

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.

Good XML Documentation (3, Insightful)

Reality Master 101 (179095) | more than 6 years ago | (#20746521)

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 (1)

WPIDalamar (122110) | more than 6 years ago | (#20746605)

And XSD with a good XML editor is better than most documentation you could produce.

Throw comments into the XSD, and it's gold.

Re:XSD (1)

msuarezalvarez (667058) | more than 6 years ago | (#20746675)

Imagine the ODF spec within comments of the schema... or the OOXML one, if you are into S&M.

Re:XSD (1)

anomalous cohort (704239) | more than 6 years ago | (#20747291)

ODF spec within comments of the schema...S&M

Right. And what about capturing mechanisms? For example if you had to take the value from one part of the XML...

for $x in doc("books.xml")/bookstore/book
where $x/price>30
return $x/title

...and put it in another such as adding it to /bookstore/premium/collection/booksover30/title

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.

Re:XSD (0)

Anonymous Coward | more than 6 years ago | (#20746815)

There are quite a few XML editors out there that are meant for technical writers. Most of them can read XSD and usually require some other template for formatting.

I used those:
* Arbortext EPIC
* Altova Authentic

There is also Syntext Serna which looks great, but I never got to using it in a real context.

There is a time tested solution: DocBook (2, Informative)

badger.foo (447981) | more than 6 years ago | (#20746693)

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.

JSON (1)

WickedLogic (314155) | more than 6 years ago | (#20746825)

Using a less difficult markup... JSON [json.org] .

Tibco TurboXML DTD Diagrams (4, Informative)

Cheefachi (970662) | more than 6 years ago | (#20747057)

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!

Slightly off-topic, but... (3, Insightful)

Mortanius (225192) | more than 6 years ago | (#20747617)

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.

Re:Slightly off-topic, but... (0)

Anonymous Coward | more than 6 years ago | (#20747935)

You must be new here?

Use Word styles (2, Informative)

Mean Variance (913229) | more than 6 years ago | (#20748003)

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.

This is a publishing cycle question... (1)

holloway (46404) | more than 6 years ago | (#20749357)

Well obviously you should provide schemas as well, so basically the question is how to do you make sure that the document and the schema are kept in sync, yes?

So it seems that it's a publishing cycle question. You should have a source document with placeholders that some later process replaces with code snippets. Your schemas could have foreign nodes that denote placeholder Ids, for to map them up.

You could use Docvert [docvert.org] which lets you make XML Pipelines from content and build plugins and conversion stages, that way you could replace placeholders from any of your schemas. It generates HTML and DocBook so you could then convert that to PDF or whatever.

my best practices (0)

Anonymous Coward | more than 6 years ago | (#20750045)

If I have to include XML, I will typically have XMLSpy format it, then copy it from XMLSpy. Inserting in this way will retain the colorization and formatting for readability.

In Word, I will shrink the text to where it is barely readable, since anyone wanting to read it can easily cut-and-paste elsewhere or simply zoom in. In doing so, I minimize the amount of space I consume with ugly XML, and it minimizes the ugly line-wraps.

But as an alternative, I prefer using Object Diagrams (not Class Diagrams) to describe the message structure in a format-independent way that is much more readable and appealing...assuming the audience can grasp the notation. I suggest this any time the explicit description of XML tags, attributes, etc is not absolutely necessary.

Sometimes... (1)

dannys42 (61725) | more than 6 years ago | (#20750239)

The only way to win is not to play.

XML is like .. (0)

Anonymous Coward | more than 6 years ago | (#20750243)

XML is like violence
If it doesn't work -- use more

Use XML (2, Informative)

frisket (149522) | more than 6 years ago | (#20750347)

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:Use XML (1)

zbend (827907) | about 7 years ago | (#20751161)

Wait a minute you have people writting documentation for xml schema that don't understand XML? Sounds like the XML schemas I have to consume. You don't work for the state of MN do you?

Re:Use XML (1)

nagora (177841) | about 7 years ago | (#20752807)

If you're serious about doing documentation, use an XML editor wi

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

TWW

Re:Use XML (1)

cprael (215426) | about 7 years ago | (#20757197)

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

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 (1)

thethibs (882667) | about 7 years ago | (#20750857)

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 as an object linked to the file (Insert|Object|Create from File) so that any changes to the file are automagically sync'd in the document. This can be a log file, a Visio diagram, or an Excel spreadsheet—anything it takes to clearly describe what you're doing. If your life is really interesting, there are also compound documents to play with.

I spend my days (and some nights) developing technical documents. I cannot conceive of using a lesser tool. I've played some with Open Office, but it isn't there yet.

Word is just right for replacement (1)

Zero__Kelvin (151819) | about 7 years ago | (#20751231)

"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."
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 now, and it has all of the needed features without all of the complexity and code bloat. Meanwhile it has devolved under M$'s philosophy that more options equals better to the user. The many features of Word are now so much overkill it is absurd, and it is quite literally impossible to test all of the interactions, which is fine with M$, since their philosophy is to test it just enough to ensure income.

Re:Word is just right for replacement (1)

thethibs (882667) | about 7 years ago | (#20762011)

Now read the rest of what I posted.

Re:Word is just right for replacement (1)

Zero__Kelvin (151819) | about 7 years ago | (#20767279)

"Now read the rest of what I posted."
You are confused in thinking that my post was for your benefit. It's great that you've " ...played some with Open Office, but it isn't there yet." When you've worked with OpenOffice, and it was on the same day you posted, your opinion may have some validity. What you meant to say was "I've played with OO, but it wasn't there yet at the time." You are a professional writer and you can't match tense in a sentence? You've probably been relying on Words flawed grammar checker for far too long.

Re:Word is just right for replacement (1)

thethibs (882667) | about 7 years ago | (#20782211)

The latest of those times was three weeks ago. Is there a new release I don't know about?

I'd like OO to do what I need it to do as well as MS Office does; I'm about to add a system and it would be nice to save the high cost of buying a whole new suite from Microsoft. Of course, I'd still have to buy Visio.

Ever heard of DocBook? (1)

jocknerd (29758) | about 7 years ago | (#20751063)

Its designed for doing technical documentation. It began as a SGML toolset but has since moved on to XML.

I don't even understand the question (1)

smallpaul (65919) | about 7 years ago | (#20751743)

I wrote an XML book a decade ago and I don't understand how it is different than documenting any other programming technology. You write chapters on various topics and you cut and paste examples into appropriate places with appropriate prose around them. Word, FrameMaker, TeX, DocBook, DITA: the container documentation technology is not particularly relevant. I mean sure, there are more sophisticated things you can do (auto-testing, auto doc-generation, XML escaped within XML etc.) but you need to tell us what kind of documentation you're trying to produce and why the no-brainer techniques are not sufficient for you.

Actually DELIVERING something, apart from polemic (1)

cprael (215426) | about 7 years ago | (#20752005)

Well, the XML docs I'm in the middle of writing currently have XML snippets embedded in the doc, and pointers to XSDs and suchlike as appropriate. The version of the doc that's going to come down the pike in about 6 months will have pointers to the schemas, cross-links to "live" XML sample code (plus the raw text thereof incorporated as appendices), etc. But that's waiting on the dev-rel server to go live. Lack of a reliable hosting space can be so... problematic.

As for tools - one works with what one has/can get. You can make this work in damn near anything, despite what the [must hate Microsoft] masses crow on about.

And yes, I've been doing this for a while. Just 20 years, this summer.

How about a graphic representation? (0)

Anonymous Coward | about 7 years ago | (#20753125)

Paste a graphical representation (aka UML or similar diagram)
That's what we do here at XYZ123 corp.
It's also useful for developers, since you get the fell for the structure pretty fast.
I may add that it would be good if a tool does that for you.
So far only Eclipse (with some XML plugin) does the trick but you must chop the image to make it fit into word or whatevr.

Multiple facets (0)

Anonymous Coward | about 7 years ago | (#20753259)

I've been tasked with complex XML documentation in the past...

The problem as I see it is that there are multiple levels of documentation.

In large systems schemas are often used in multiple places; they all use the same schema but they use it in different ways.

An order for 1 item may be accepted from a customer; expanded by technical sales; automatically validated and corrected; translated to different parts-lists for delivery planning; have existing inventory added for connectivity; translated to vendor parts - and all in the same schema (some customers provide more data so interact lower down the stack...).

So they all have some things in common: core technical (data types, syntax rules for the address data etc)
Then there is general information which is common to multiple systems (use of a shared ID from inventory system A for systems 1,2 and 3 but inventory system B for 4 5 and 6)
Then there is stuff which is specific to an interface (even though this value Y is optional in the schema; we need it if that value is set to X; oh and you can't do this...)

Embedding anything beyond the simple stuff in the schema is asking for trouble (in this situation).
Personally I've used embedded docs in the schema where possible. Usually explaining the schema structure and general aims.
Then there's a report that describes the schema usage in eg order processing. This puts a few paragraphs around each element or logical group. This often includes or references inter-system translations.
Finally there are interface specs/reports which comment on specifics above and beyond that detailed elsewhere - the logic that determines validity; the specific range of values allowed at a point. Which optional elements are actually mandatory under what circumstances...

Just use styles (1)

kikito (971480) | about 7 years ago | (#20753619)

Create an specific parragraph style (i.e. XML code) for the XML bits you want to put in your document. In terms of borders and background, make it as complicated or minimallistic as you wish, but I strongly suggest using courier new our any other monospace font.

You may also find useful to tag every document with a caption, so you can reference it later on (and do things such as "see the example on page xxx", with xxx being a reference).

description, diagram, example, schema (1)

kwatsen (1162339) | about 7 years ago | (#20753701)

I hate Word, but I use it for specifications that need to be available off-line because it provides the best printable-output of the various source-formats my organization allows.

My technique is still evolving, but I currently specify an XML format by first describing its purpose/context in plain-text, followed by a UML class diagram to visualize the information it captures, followed by an XML example, followed by its XSD. For the class-diagram, I use WSD so it will print well and I scale it so that it fits on a single page. I put both the XML example and XSD into a "table" containing exactly one cell with its background shaded to a light-grey, borders set to 0.1 inch, font set to Courier New, and manually add a line-return and/or spaces to address any line/page-wrapping that may occur. For the XSD only, I add a single-space before and after each xs:element and use bold on the "name" attributes.

Note: when designing a format, I actually start with the UML class diagram, so putting it into the spec is really a non-effort - especially since the UML tool I use (Borland Together) can paste it directly into the Window's clipboard from which I can then Ctrl-V to get it into the Word doc.

Choose a good schema language (3, Informative)

srussell (39342) | about 7 years ago | (#20753759)

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

Re:Choose a good schema language (1)

Philosomatographer (744211) | about 7 years ago | (#20753903)

RelaxNG is absolute crap, and it attempts to regress the world back to something similar to DTDs. In fact, an equivalent DTD would look very similar to the RelaxNG compact you posted. XML schema is not perfect (and sometimes a little rigid, compared to better (and fundamentally different) approaches such as RDF/OWL.

What you are doing, is constraining the structure of a document (whoopy dooh). What XML Schema is, is an object-oriented data language with classes, specialisation, polymorphism, etc. If you are an XML document writer, you might not see the benefit of this. If you are a designer or a developer (and have to, for example, transfer the state of an object between a Java object representation, and XML) you will understand. With XML Schema, an xml document becomes an instance of a class (an object).

XML Schema is conceptually at a whole level above RelaxNG and DTD, and RDF/OWL is - again - conceptually at a whole level above XML Schema.
You clearly have no idea what you're talking about - please research your facts before asserting them.

Describe the objects (1)

oglueck (235089) | about 7 years ago | (#20754629)

We use XML a lot to pass business objects around. Often through web services (SOAP), but not only. We never document the XML structure itself (although there is some documentation in our WSDL files). Instead we describe the business objects. Each object has a name and a list of fields. The field has a type (primitive or Object type), a length, a multiplicity (1, 0..1, 1..n, 0..n usually) and a description. All the semantics go into the description. The meaning of some fields may depend on the performed operation. This should be described together with the description of the operation. The objects and fields are then represented as XML elements with the same name. We hardly ever use attributes.

Sample:

Object: Person
Fields:
name  string(32)  1     The last name
fname string(32)  1     The first name
dob   date        0..1  Date of birth
kid   Person      0..n  The persons children

XML:
<Person>
  <name>Doe</name>
  <fname>John</fname>
  <dob>1974-12-31+02:00</dob>
  <kid>
    <Person>
      <name>Doe</name>
      <fname>Harry</fname>
      <dob>1991-12-1+02:00</dob>
    </Person>
  </kid>
  <kid>
    <Person>
      <name>Doe</name>
      <fname>Sally</fname>
      <dob>1993-12-2+02:00</dob>
    </Person>
  </kid>
</Person>

Re:Describe the objects (1)

teebob21 (947095) | about 7 years ago | (#20764815)

This is exactly how the workforce management application I work with passes its transactions. When I started the job, I knew nothing about the backend of the app, since I had only used it in the field, and thus seen the frontend. By the end of the day, I was reading log files and XML transactions as they flowed. I was able to understand the data and the schema immediately because it contains intelligently crafted tagnames and structure. Maybe not all XML is like this, but the gobbledygook I see each day is well formatted.

Prior to taking this job I had no experience with XML whatsoever, only a basic grasp of HTML. I still don't know much about XML, but at least I can read it.

try to preserve XML color of your editor (1)

hswerdfe (569925) | about 7 years ago | (#20754659)

find a text editor that can color you xml, I use Programmers Notepad but there are many that will do the job.
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.

Hybrid approach - schema + customized HTML (1)

styzygy (514282) | about 7 years ago | (#20755619)

My company makes software that uses XML messages as the interface between a user's invoicing system and our system for tax calculation. The schema for the various messages is well-commented, but we felt the raw XML wasn't as human-friendly as we'd like.

We tried output from XML Spy which was an improvement for some purposes, but what we really wanted was a succinct table that listed each element/attribute along with its occurance info, valid values, and a text description. We initially did this manually in Excel, but then we internally-developed a tool that reads the XML and outputs the info in a human-friendly HTML table.

Our XML documentation includes the raw schema + the HTML reference tables + sample messages. We provide this doc in HTML format with a frameset to provide table of contents, search, and index (currently WebHelp output from RoboHelp, but we're in the process of switching to Author-IT).

In soviet russia... (0)

Anonymous Coward | about 7 years ago | (#20755759)

Docs embed XML!

uh, no.. it is microsoft that does that when I come to think about it.

heres' what I do (1)

sonamchauhan (587356) | about 7 years ago | (#20763247)

I recommend two things:

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 cases where a subelement can be only one of several different types - in this case, you could use different tables, or even auto-include Word tables.)

2. Pretty print the document using a text or XML editor so XML is properly indented. Remove contents and closing tags that occur on one line so that only the structure of the XML is shown. For instance, remove '20020302T00:00:00</RequestedDeliveryDate>' from the line below

<PurchaseOrder>
  <OrderHeader>
    <POIssuedDate>
      <RequestedDeliveryDate>20020302T00:00:00</RequestedDeliveryDate>

You may want to convert tab indentation to spaces at this point so that space is more efficiently used.

3. Paste the document into a word table with additional columns to add usage notes, and other metadata for each element. This is best done with the page setup in portrait mode.

It's difficult to illustrate this on Slashdot, but the snippet below sort of illustrates the idea using wiki lingo


XML Element | Notes | Mandatory/Optional | Mapped to Backend
<PurchaseOrder>
  <OrderHeader>
    <POIssuedDate>
      <RequestedDeliveryDate> | the date ... blah blah blah | O | Yes


This Works For Me (2, Informative)

ToxicBanjo (905105) | about 7 years ago | (#20796689)

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
Check for New Comments
Slashdot Login

Need an Account?

Forgot your password?