A tale of two documentations

From time to time I find myself needing to integrate our system with some external vendor, and that usually means writing an XSL transform.  Last week I had 2 completely different experiences dealing with documentation from a couple of vendors.  Let's compare, shall we?

Company #1:

Company #1 is a large internet video distribution company, which "empowers content owners... to reach their audiences directly through the internet."  And they are very good at what they do.  They have probably fed you a video through some web site and you don't even know it.  So when it came time to generate an xslt to integrate with their system, I sat down and read the 4 separate documents that describe how to generate the xml manifest.  For the next few days, I played email tag with their support team as I fixed one issue only to unveil another.  It turned out that their documentation had a few errors.  You know, little things like incorrect tag names, required fields that weren't specified as required, and the fact that their xml parser is case sensitive.   That last one really steamed me.  I have since used the documentation as firewood to fend off the chill that came over me after excluding a distribution region by using a tag named "allow" (no attributes on this tag).

Company #2:

On the opposite end of the spectrum is company #2.  Its a small, very specialized, service provider with a single developer currently dedicated to this particular project.  Instead of getting a word or pdf document describing the xml creation process, I was given a highly commented DTD document.  And, surprise, this integration worked the first time without errors. 

I've conversed with several of my colleagues about this and most of them fail to see the awesomeness of this approach.  So, for those of you who missed it, here's why it is so awesome.  Not only was the documentation completely correct, it couldn't have been incorrect.  By passing me their DTD, they were saying "Here is the code that we use to validate your response.  If it validates for you, it will validate for us as well."  In this instance the code itself was enough.  They didn't even have to send an example xml file.  XmlSpy generated one in less than a second. 

I also feel that the comments left directly in the code, in this case the DTD, are a much clearer reflection of the author's intent.  This is the author spilling out his thought process, not just some dud that's been told to document a process by Friday. 

This experience just validates my belief that large external documents are slowly going the way of the dodo.  I've felt this way for a while now.  I'm a big fan of less documentation that is more useful.  Think about it.  End user's don't want to read a manual anymore.  They've come to expect inline help and most are even trained to look for tooltips. 

Song of the day:
State of the Union - David Ford - I Sincerely Apologize for All the Trouble I've Caused