I was thinking about a comment I made to my intern last week. She has been studiously attending to all the different things I do in my day (what many people consider a well-guarded secret!), and over the last few days we were writing documentation for a customer I’m helping build out a brand new Enterprise Data Warehouse.
As part of documenting the process for data extract, load, and transformation (ETL), I said off-hand that people don’t read documentation unless there’s an emergency. This is important to consider because it has a direct bearing on naming conventions, document flow, using plain language, and so on. People will not read the entire document through from start to end. Senior executives might read the appropriately-named Executive Summary, the Information Technology department lead will spot-check the technical content, and it will gather virtual dust until something breaks and no one from the original team is working on the project any longer.
I acknowledge that this appears to be a flippant point of view, especially given that I write technical documentation, blog posts and books. Bear with me then as I take a moment to write about the weather.
Calgary has wacky weather. On the evening of September 27, 2019 (Friday of last week), we had our first snow of the season. Normally the first snowfall starts somewhere between early and mid October, though it is sometimes delayed until after Halloween. But not this year. It has snowed hard all weekend, and there are piles of snow everywhere.
This has, of course, caused several accidents on the roads — with over 160 traffic incidents reported on Monday morning already — more than 30 of which were hit-and-runs. Last week there was barely-restrained panic across the city in terms of getting snow tires (also known as “Winter tires”) fitted. When I called my car dealership earlier in the week to arrange my own tire swap (I had already planned it to coincide with the annual oil change next week), the service representative described how chaotic it had been for them already. I told them that I had looked at the long term weather forecast, and noted that warmer weather would return for another two weeks toward the end of the month, at which point I wanted to book in my vehicle for the oil change and tires to coincide with that. To both of our surprise, they informed me that the day I asked for was wide open. In fact, the panic they described was focused on getting tires as soon as possible before the snow fell, so I could have even done my tires that week.
I drove for some years in South Africa before moving to Canada, and my general opinion is that Canadians are better drivers overall in comparison, Canada’s Worst Driver notwithstanding.
Until it snows, and then all bets are off.
Cities like Edmonton and Lloydminster — where I first lived in Canada — receive a significant amount of snow for Alberta (this isn’t a contest, Winnipeg). When it gets cold, it is extremely dangerous to drive without winter tires. The rubber compound on all-season tires is not designed for the extreme conditions we experience, plus winter tires provide a safer grip and more traction.
But it’s still early October. Even without our famous chinook winds (periodic warm winds off the Rocky Mountains that can melt the snow overnight), it’s just not quite time for winter tires. The average daytime temperature is expected to go back above 12 degrees Celsius (my personal tipping point) next week again.
How does this relate to documentation? Think back to the vehicle dealership that was inundated with people who panicked at the first snow of the season. Were they right to panic? Taking just one aspect into account — namely the conditions of the roads as I write this — we might be tempted to say yes. However, the average daytime temperature is hovering around freezing and will be up again by the end of the week. That is time enough to arrange a less stressful moment to put on winter tires. Chaos averted. It does mean taking extra care on the roads now with the unexpected snowfall, but that’s a conversation about safe driving distance, not winter tires. There’s no excuse for a hit and run.
My recommendation is that you don’t leave it for an emergency situation before reading your documentation. Plan your maintenance windows. Don’t rely on a single data point to make an informed decision. And if you see a gap in your organization’s knowledge, write it down! Whether it be technical documentation written by your IT department, or outsourced to consultants like me, those words matter and should be considered and absorbed in a safe and warm environment. Being prepared means understanding what’s in there and being able to think clearly when emergencies happen. It means knowing to drive carefully during an unexpected snowfall, and take it in stride. You don’t want to be fighting to get into the vehicle dealership, just as you don’t want to be reading a strange document at 3 am on a Sunday morning using the search feature because someone pushed a bad configuration file to all your sites.
Leave your thoughts in the comments below.
Photo by Tyson Dudley on Unsplash.