Shibboleth authentication via simpleSAMLphp broke on one of our apps when the system clock on the Shibboleth server drifted more than a minute into the future.
I am not the administrator of the Shibboleth server. But it occured to me that even with no shell access to the server, I could detect clock drift by examining the time stamp in the HTTP headers from the server.
After having used Lightning Touch to greatly speed up the interface for UCSF Mobile, it was time to improve load and render times.
What really set me down this path was discovering Mobitest. Their results will assign a decile for your site’s load time. Being unhealthily competitive, I of course wanted to see m.ucsf.edu in the top tier with the adorable “90th Percentile” indicator.
I could have documented what I did in a more conventional way, but here’s the thing: I wouldn’t have been as meticulous. I would have included what I felt was the minimum that I would need to repeat the task. I would have glossed over things that were obvious to me because they were fresh on my mind. But after months of not thinking about the task, going back to that sort of documentation would have meant that there would be substantial gaps.
By creating something that would live on YouTube, where I knew others would see it, I was motivated to be complete in my documentation.
It’s tempting to focus on things that aren’t very important when it comes to documentation. People like to create documentation templates, for example, wherein they try to have a section for every imaginable category of content that might be in a document. Most of the time, there will be tons of unused sections when the real documentation is written. And then the technique backfires. If someone is given a documentation template that is not even wrong, then there’s an excellent chance that they will just fill out the minimum that they can get away with and move on to a more meaningful task. In other words, they will just create bad documentation.
Of course, that’s not to say something ridiculous, like “All documentation templates are bad.” A template can be great for someone who doesn’t know where to begin or otherwise wants direction, especially if the template is reasonably succinct. (That said, an example of stellar documentation is usually better than a template.)
And there’s a lot that can be improved in my YouTube documentation. (A video is a terrible way to pass along a shell script.)
But, ultimately, nothing beats a documentation method and format that excites the documenter.