We, as XML geeks, all have to do with understanding XML structures we didn't design ourselves. It might be a programming language written as XML, a library configuration file we need to change or data that needs filling. Whatever it is, we need to comprehend the format: the elements, the parent-child relations and the attributes. Most important of course is the meaning of it: how can we use this XML structure to bridge the gap between our intend and the workings of the software it's going to be processed by.

Most of us will probably have been on the other side of this problem: We designed a nifty XML structure and needed to explain this in such a way that others can and will use it (and, as an important side-effect, are mighty impressed by our elegant, intelligent and beautiful design). How to explain an XML structure so users can make the most of it? More often than not this also has marketing value: A well constructed and intelligible explanation might convince people to use your product/library/programming language.

Neither side is easy. We probably all have experienced the frustration of wrestling with a half understood and sloppily documented XML format as input for some piece of software that stubbornly refused to do what we wanted it to do. Or, on the other side, the sinking feeling of having to document this nice but complex XML structure, not really knowing how to do this, but realizing it will take a lot of time.

This paper will look at the problem of documenting XML structures from various angles: consumer, producer, the structures themselves, supporting software, etc. It will then focus on the production side. Spoiler alert: There are no quick and easy solutions and at the end there is, unfortunately, no GitHub repository containing an auto-XML-structure-document-writer-application… sorry. However, with a little thinking upfront and a bit of automation, the task of documenting XML structures can become more manageable and maybe, for some, even enjoyable.