Documenting an XML Schema Definition (XSD) can be a tiring process. You first load a file in an XSD viewing tool like XMLSpy, you then make screenshots of the areas of the definition you want to display and finally, you paste them into your documentation. Of course you have to repeat the entire process whenever the file changes in any way.

Avisi prides itself on being a cutting edge development organization so we felt strongly we needed to find a solution to this problem. Since we use Confluence as our documentation platform we chose to build a Confluence plugin: the XSD Viewer for Confluence.

With the XSD Viewer plugin for Confluence, technical documentation writers now have the option to simply attach the XSD file to the Confluence page and then to use the plugin macros to display either a graphical view of the XSD or a table with an overview of the elements and its attributes.

I will demonstrate this with an example. For the purpose of this blog, I will use the Atlassian plugin XML (the XSD’s can be found here: https://bitbucket.org/atlassian/atlassian-xsd).

To get started, we create a new page in Confluence that will be the starting point for the documentation. We add the XSD file as an attachment. For this example, I used the atlassian-plugins-2.7.xsd.

Now that the XSD is in place we can start writing the documentation. The first step is to create a structural overview of the XML. So in edit mode, I add the macro {xsd-image}. In the Edit Macro screen I select the XSD and fill in the starting element, in this case the root element atlassian-plugin. To see the children of the root element, we need to set the depth to 2  (See the image below).

Now we have a visual overview of the plugin, but information for the different elements is still missing. We can display this additional information in a seperate table with the {xsd-table} macro. Once we set the starting element and the depth, the page should look like this next screenshot.

Now we have documented the root element, we want to make documentation for each element that can be placed into the any element. We will add the different elements as child pages to the current page.

Let’s demonstrate this with the web-section element. Add a page to the current page and call it Web section. Now add the xsd-image macro to the page. We of course want to reuse the XSD file attached to the parent page. So start typing the name of the parent page in the Page attribute in the Edit Macro screen. The field will be auto-completed based on the text you enter. Select the correct page and select the XSD attachment in the next attribute. Now use web-section as starting element with a depth of 0 (unlimited depth). Now alle elements under the web-section element are displayed. Save it and check out the result!

Now you can complete the documentation with some examples and extra instructions for the reader and the page is ready.

Whenever there is an update in the XSD, simply overwrite the XSD file attached to the page and all images and tables will be updated automatically.

If you want to try it out for yourself, download the plugin in the Atlassian marketplace.