XML element documentation

What is a good (or at least sufficient) documentation format for our XML structures? We've already talked about the importance of introductory text and examples so let's not talk about that again. Let's look at how to document the basic building blocks of XML: elements. I'll list some requirements first an then talk about what I made of them.

When I started out writing the XProc book I thought long and hard about how to do this. What I came up with is the following:

So is this it? No, absolutely not. I regularly catch myself changing this or that little detail (especially when the inspiration for writing prose is temporarily missing, the equivalent of doodling around…). There are still some things I'm not totally satisfied with but unsure on how to proceed or decide. For instance the order of attributes/child elements. Should this be alphabetical or in order of importance? And if the latter, how do you decide on importance? It's probably something that is never finished but one thing I do know: it's slowly getting better.