I hate Word, but I use it for specifications that need to be available off-line because it provides the best printable-output of the various source-formats my organization allows.
My technique is still evolving, but I currently specify an XML format by first describing its purpose/context in plain-text, followed by a UML class diagram to visualize the information it captures, followed by an XML example, followed by its XSD. For the class-diagram, I use WSD so it will print well and I scale it so that it fits on a single page. I put both the XML example and XSD into a "table" containing exactly one cell with its background shaded to a light-grey, borders set to 0.1 inch, font set to Courier New, and manually add a line-return and/or spaces to address any line/page-wrapping that may occur. For the XSD only, I add a single-space before and after each xs:element and use bold on the "name" attributes.
Note: when designing a format, I actually start with the UML class diagram, so putting it into the spec is really a non-effort - especially since the UML tool I use (Borland Together) can paste it directly into the Window's clipboard from which I can then Ctrl-V to get it into the Word doc.
Slashdot Mirror
I hate Word, but I use it for specifications that need to be available off-line because it provides the best printable-output of the various source-formats my organization allows.
My technique is still evolving, but I currently specify an XML format by first describing its purpose/context in plain-text, followed by a UML class diagram to visualize the information it captures, followed by an XML example, followed by its XSD. For the class-diagram, I use WSD so it will print well and I scale it so that it fits on a single page. I put both the XML example and XSD into a "table" containing exactly one cell with its background shaded to a light-grey, borders set to 0.1 inch, font set to Courier New, and manually add a line-return and/or spaces to address any line/page-wrapping that may occur. For the XSD only, I add a single-space before and after each xs:element and use bold on the "name" attributes.
Note: when designing a format, I actually start with the UML class diagram, so putting it into the spec is really a non-effort - especially since the UML tool I use (Borland Together) can paste it directly into the Window's clipboard from which I can then Ctrl-V to get it into the Word doc.