Interfaces and Document IDs – A Rant

Please forgive me if this sounds like a rant, but I’m very annoyed. Someone who should know better has without warning changed a public interface, with the inevitable effect that dependent systems, in particular my blog, have broken. The offender? The mighty Microsoft.

Regular readers will know that I’ve highlighted several articles published in Microsoft’s Architecture Journal. A week ago I went to post a note on another article, to find that all my previous hyperlinks were broken. Thanks to my regular correspondents Richard Veryard and Arnon Rotem-Gal-Oz I discovered that the cause is an internal reorganisation within Microsoft, and there is a new web location for the journal, although it wouldn’t surprise me if that changes again. (To add insult to injury, the new URLs are very cryptic, and don’t paste easily into my blog!)

Now if you follow Microsoft’s advice when building systems, interfaces should be immutable. Otherwise you just don’t know what will break. The Microsoft advice is to never change an existing interface – if you need a different one, create a new interface, or at least a different version. And maintain the old one as long as dependent systems need it.

Microsoft are actually very good (not perfect, but quite good) at following this rule in their software systems. But they don’t seem to understand that the same rule should apply to that big public interface called the website. There are, of course, perfectly good strategies which would avoid this problem.

First, don’t try to reflect internal structural changes in the MSDN website. Doing so is like changing a system’s interface just because the implementation has been updated – the opposite of good practice. The public interface should be independent of implementation details.

Second, if you must create a new interface, keep the old one working. In systems, you can usually wrap the new interface to mimic the old. The same is true for a website. A set of auto-redirect pages at the old addresses, and I would never have even noticed the change.

Unfortunately Microsoft have done neither of these. And they seem to have a corporate blindness to the fact that documents are interfaces too. MS SharePoint is based on a web idiom, in which documents are identified by their position in a hierarchy. Re-arrange the hierarchy, and any external references or cross-references suddenly break.

Professional-quality document management systems don’t do this. They identify and control documents via a unique, immutable key into the underlying repository, and the primary document access via this key is guaranteed. Of course, you also want to show the document in a hierarchical structure, but any such entry is just a pointer to the underlying document. And if you want to change the hierarchy, or expose the same underlying document at multiple places in multiple hierarchies, it’s easy to do. The world of blogging has a similar concept, with “permalinks” which (should) survive a reorganisation.

Memo to Microsoft: links are interfaces too!

Leave a Reply

Your email address will not be published. Required fields are marked *