views:

141

answers:

4

When it comes to documenting the structure of XML files...

One of my cooworkers does it in a Word table: alt text

Another pastes the elements into a Word document with comments like this:

<objectRoot>
 <v>
  <!-- Current version of the object from the repository. !-->
  <!-- (Occurance: 1) -->
 </v>
 <label>
  <!-- Name of the object from the repository. !-->
  <!-- (Occurance: 0 or 1 or Many) -->
 </label>
</objectRoot>

Which one of these methods is preferred? Is there a better way?

Are there other options that do not require third party Schema Documenter tools to update?

+2  A: 

Personally, I would prefer seeing it in XML (the 2nd way).

Putting the elements in the table won't tell you clearly which elements are which elements' parent child and so on. Putting it in XML is rather clearer and I can see what's going on.

thephpdeveloper
+4  A: 

You might try documenting it by creating an XSD schema which would provide a more formal specification of your XML. Many tools will generate the XSD for you from sample XML as a starting point.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"&gt;
<xs:element name="objectroot">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="v" minOccurs="1" type="xs:string"/> <!-- current version -->
      <xs:element name="label" type="xs:string"/> <!-- object name -->
    </xs:sequence>
  </xs:complexType>
</xs:element>
</xs:schema>
zac
haha, posted at the same time
TandemAdam
Good idea. Although I am a little worried that my documentation will never get updated because someone now needs another tool to update it.
joe
@joe: You won't require a tool to maintain it. You can use something like XmlSpy to generate the XSD initially from your XML instance documents and then you can use notepad to maintain it going forward as they are just text documents.
zac
@zac: You do if you think of the overall process. (1) Someone reads documenation. (2) sees a change is needed. (3) Go back to the xsd source (4)Update the xsd source (5) Find tool such as XmlSpy to regenerate the documentation. having to get another tool is a burden and limits the use of this form of documentation.
joe
+2  A: 

Showing it in a table has its limitaions e.g. mulit-levels of nested children, but for a simple XML structure I think this would be fine. For anything with more than one nested level I would prefer the XML way.

An even better way would be to create an XML Schema (XSD) file. That way, you get the benifits of seeing it in XML, and you can check the file after the data is inputted against the schema file using some software.

For a great series of tutorials on XSD check out w3schools - XML Schema Tutorial

TandemAdam
+6  A: 

I'd write an XML Schema (XSD) file to define the structure of the XML document. xs:annotation and xs:documentation tags can be included to describe the elements. The XSD file can be transformed into documentation using XSLT stylesheets such as xs3p or tools such as XML Schema Documenter.

For an introduction to XML Schema see the XML Schools tutorial.

Here is your example, expressed as XML Schema with xs:annotation tags:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"&gt;
  <xs:element name="objectroot">
    <xs:complexType>
      <xs:sequence>

        <xs:element name="v" type="xs:string">
          <xs:annotation>
            <xs:documentation>Current version of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

        <xs:element name="label" minOccurs="0" maxOccurs="unbounded" type="xs:string">
          <xs:annotation>
            <xs:documentation>Name of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
Phil Ross
+1 for going the extra mile.
zac
Well played Phil, well played ;)
TandemAdam
Good idea. Although I am a little worried that my documentation will never get updated because someone now needs another tool to update it.
joe
@joe: an option is to use that <schema> file directly *as* the documentation - with the bonus that you can use standard tools to produce further documentation; and also use the XSD to to check (validate) the XML; and to exchange with other parties who might need to understand your format. Because it's a standard, learning to use it becomes a valuable skill for you in other tasks/employers - and similarly, it's a common skill in the employment pool, so replacements can be found. Unfortunately, it's an awful standard in that it's harder to read and write than either of your examples.
13ren
@13ren: Yes, it is unfortunate that the structure of an XSD file is so hard to read. I would not feel comfortable passing it off as "documentation". It would be nice if there was a tool that could open an XSD file in a user friendly view. (As apposed to a tool that generates a readonly file for viewing). Or even a tool that generates a Word document version of the documentation would be nice.
joe