Documentation written to the broader audience

DOCUMENTATION! Yikes!

If you’ve ever architected and/or lead a project I’d bet you’ve done plenty of documentation. Either some reference docs, requirement docs, maybe some pretty pictures of the system architecture, throw in some UML, TOGAF 9, a data model, a domain model, wireframes. Odds are you wrote the ‘important’ stuff upfront: this would be requirements, architecture, models. Or perhaps you’ve had an interested investor want to see the architecture and they bring in their technical bobo “their you” and thus you scramble to update (or create) the documentation…ah, what we do for money. Anyway, you write some documentation, you change the system, it evolves and yada, yada, yada…it ends up stale. (Never-mind customers with undocumented legacy systems and being asked to support those, that is a story for another day.)

At some point there is documentation that is actually consumed. An API reference, or the old SOAP doc, a feed you provide to be gulped up daily with actions, or just some transport reference. You’ve written, I’ve written them, they are as boring as this post and generally assume some basic if not high-level understanding. Retail audio distributors and retailers tend to XML as their format of choice and I was impressed with some documentation for the latest export I’m working on for a record label customer of mine.

XML Considerations
This information is delivered to REMOVED to protect the innocent in XML format. XML is a standard method for exchanging data in a machine-readable format. It may look strange at first, but it’s really not that complicated. If you keep a few simple rules in mind you’ll have no problem:

  • All data is enclosed by tags, for example: <Title>Yellow Submarine<Title/>
  • Tags are case sensitive. <TITLE> is not the same as <Title>
  • An element consists of an opening tag, a closing tag (with the backslash before the tag name) and any data contained within the tags.
  • Elements can be nested. For instance, your file will have an <ALBUM> element, inside which one or more <TRACK> elements will be nested, and each of the <TRACK> elements will in turn have other elements nested inside containing information about each track.
  • Order is important. You must submit the elements in the exact order specified.
  • One element includes a value inside the tag. This is called an attribute: <OVERRIDE CURRENCY=”USD”>5.00</OVERRIDE> In this case CURRENCY is an attribute of the OVERRIDE tag.
  • Each element must only contain a single value. Do not include a comma-separated list of values in any of your elements.
  • Please do not submit empty tags in your XML file. Instead, please omit the element. Empty elements cause errors and fail our ingestion process.

(continues) For a full XML specification please refer to Appendix A.(continues)

The overview was well written, focused, and directs the consumer to the appendix for more information. I’m unable to recall including information like this in my documentation; granted my budget is likely the same as their dry-erase marker budget. Still, well done.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s