Let's step to the other side and imagine we have to document some non-trivial XML structure. If there are no previously set rules and guidelines, we're faced with some tough choices: how deep or shallow should the documentation be, what format are we're going to use, how are we going to produce and maintain it?
These questions need in answer, but maybe we should start with acknowledging something important: for most people it's not a pleasant prospect at all!. You're deep-down in some code that will be used by others, you created some clever XML format, and suddenly you realize that, for people to be able to use your skilfully designed contraption, this format, that grew a little out of hand, needs documentation. Argh. A depressive sinking feeling overwhelms you… But why is that?
Creating documentation means stepping out of your "knowledge bubble", which is a very, very hard thing to do. You have to step back and try to imagine you're new to all this. What does a fresh user of your software/format needs to know? What is important background, overview and detail information?
Creating documentation is a lot of work.
You're (probably) a developer, not a technical writer, and documenting is not your favourite cup of tea.
Even when you just start writing, you'll soon realize you need a format, a consistent way of describing things. Not only for the reader, but also for yourself. Documenting structures by following some format is really much easier than just typing along and making things up on the fly. But which one? Sigh…
Once you have it, you're obliged to maintain it. This means that changes in the software now also require you to revisit the documentation. This can lead to all the phenomena we know from maintaining software: from just a few keystrokes to extensive refactor and overhaul operations.
Sometimes, while programming, you get carried away and in the end your XML structure turns out to be so complicated, documenting it is hardly doable.
So how to approach this? Before we go in to this, let's make a little side step and look at something that might be going through your mind already: Of course the XML structure in question has a schema of some sort. Can't we use that for (generating) documentation?