What is the best way to represent an XML file in a Design document?

Question

What is the best way to represent an XML file in a design document?

For table we typically show it as

Name          Type

CustomerID   {GUID}

For XML do we just paste the XML in the document?

Answer 1

It depends entirely upon the target audience.

In the past I have used:

• xsd schemas when dealing with technical people
• XML examples when needing to see expected usage
• A simple table, much like what you have shown for a DB table
• Third party visualisers when wanting something a little bit prettier.

One nice thing about using a simple table is that it can give you a way of expressing the cardinality of elements to people who are not familar with xsd.

So you have something like:

Element Name          Type        Mandatory     Max Occurs
-----------------------------------------------------------
Customer Name     |   string  |   Y          |  2

---

A third pary tool I can thoroughly recommend is XMLSpy from Altova - they offer a trial period so you can give it a go for yourself.