If a genie jumped out of my coffee right now and offered to grant me a wish, here’s what I’d want (world peace is overrated):
I want a way to put a sunset date onto technical web data,Â so that I can find relevant technical information instead of the one “Introduction to Tomcat” that 5 gzillion people downloaded 6 years ago, and that eventually reveals itself to be 3 versions out of date, but still shows up at the top of the hit list.
I would love to have a way to know that when presented with two webpages, each describing two COMPLETELY different ways to do something without mentioning a date or a version or a platform, I can pick the one that isn’t going to waste 6 hours of my time.
Scope.Â Context.Â That is what I wish for.Â Â A consistent way to determine scope and context.
This is my own reminder to myself, to write documentation that includes scope and context, right up front.Â Whatever I can go back and add scope to, I will.Â I will imagine that it is 10 years from now, and .NET Framework 27.2 has just been released,Â and I want to put that on my machine along with Higgins Framework 10.7b. Â Â Either my documents should be still-relevant, or instantly dismissable.Â If I can accomplish that, and keep it up, I’ll be happy.
The worst documentation is the vendor-branded stuff, of course.Â No author.Â No date.Â No version.Â Â Erg.
Ain’t it the truth. Especially when you’re just digging in to some area of inquiry that’s new to you.
The trick to having a sunset capability lies in the prior document knowing when the latter document has superceded it, right? I guess for tech stuff you have release numbers, but then how do you know what’s happened when LID combines forces with OpenID and the numbers switch to a different sequence? Time for a 2.0 Yahoo that distributes the task of organizing the sequencing of the latest memes? Count me in.
The key is not to have a sunset date, but to make each version of software so wildly incompatible with all other versions that its documentation cannot be mistaken for that of another version. “Hmm, config files written in Klingon… that’s version 3.2.”