Tim Bray recently posted that both MSDN and Sun Developer Network sites don’t validate (aka borked), and then Scoble complains that Bloglines and Newsgator are not OPML Editor compatible. On the surface you would think that both of these issues were caused by developers not reading the spec, and developing according to it, but you would only be half right. I’m not known to be a W3C cheerleader, but I’ve got to give credit where credit is due, and mention that the HTML and XHTML specs are easy to find and (relatively) easy to read. I can’t say the same thing for the highly touted Atom and OPML specs.
I’ve tried to write specs for various XML specs (some internal, some public stuff that I’m working on), and I know it is not an easy thing to do. Specs for XML formats that are built using open source projects are even harder to create, because they do not usually have a large team behind the project, usually just a couple developers. Asking a developer (no matter how great of a developer they are) to double as a Business Analyst is just asking for trouble (we need more BAs, but that is a whole other rant).
I’ve mentioned the borked OPML Editor back when I released my OPML. The OPML site would seem the place to go to read the current spec, but Dave Winer’s OPML Editor creates OPML 1.1, but public spec is 1.0, and a spec for 1.1 is nowhere to be found. My OPML file was created with Dave’s tool, but does not validate when run thru the OPML Validator (which validates 1.0 only). So, Robert, how can you expect Bloglines and Newsgator to comply with a “spec” that is only buried in a tool? And even if the public spec was up to date, try reading the spec without looking at the example files. Go on, I’ll wait. Now try to tell me that you can create a valid OPML doc. Unless you have written OPML before, or have seen what Dave expects, you’ll be hard pressed to do it right the first 1000’s times. Odds are you will give up and take a look at what others are producing, and make yours look like theirs. That’s not a spec, that is cut and paste. And to make matters worse, OPML doesn’t use namespaces (that’s a known Dave issue, but the average XML developer might not know that).
It may seem like I’m picking on Dave, but I’m not (really, I’m not). Check out Sam Ruby’s favorite spec ATOM and it’s syndication format spec. Quick, by looking at the first part of the page, which version is discussed? You have to scroll down to the sample feed and assume that the version is embedded in the namespace. Not very intuitive. And what about the previous versions, and upgrading to the latest. You can’t find it on that site. Nor can you find anything about previous version. You have to search the web (here’s what I’ve been using). Just last week I was talking to a developer that builds some very cool blogging software, and he had to resort to mimicking other ATOM 1.0 feeds, instead of reading the spec, because the spec was inadequate for them to develop from.
It is these types of road blocks that cause very good specs not to be adopted. If you want developers to use your spec, you have to make it easy for them. The people writing these specs are some of the best and brightest in the world, and sometimes lose sight in the fact that the average developer has a hard time grokking this stuff.