I can’t prove this, but I suspect that most IT and developer types tend to work under pressure. Those folks are either in the middle of a big project with a looming deadline (or a recent catastrophic crash), or they’re struggling to learn a whole new technology. Either way, they’re looking to master the material as soon as possible.
Broadly speaking, there are three categories of training content: product documentation (like the man files that come with Linux programs), learn-from-doing user guides, and in-depth (700+ page) books that are heavy enough to substitute for military ordinance. Of course, there are loads of resources that straddle two or more of those categories, but I think this is a decent working taxonomy.
Now, each kind has both strengths and weaknesses. Product documentation tents to be complete, and often instantly accessible, but it can be difficult to find the information you’re after from the middle of an ocean of dozens or even hundreds of arguments and use-cases that don’t interest you right now. It’s also very hard to retain all the important details you might encounter when its presentation is so formulaic.
User guides – with their paste-this-here and paste-that-there style – are excellent at getting you to specific goals quickly, but they might sometimes leave out important background information. They might also be less useful if the case you’re working on right now is just a little bit different – or if the one you’ll be working on next week isn’t quite the same.
In-depth books can be just right for providing a topic’s full historical and technical context and – when well executed – for teaching the troubleshooting tools that will make it possible for you to attack and solve future challenges on your own. One thing these generally do not provide, however, is speed.
Naturally, there will probably be times when you’ll call on resources from each category…depending on your immediate need and on what’s available. But, in general, how do people tend to learn best?
Let me illustrate the question with an example from my own career. On the first day on a new job as a system administrator, my boss told me to start off by building my own workstation. He dictated to me the way it should be built and then added that I should configure it to get its NTP service from a local server. I smiled, nodded, and turned to go, while trying to remember what NTP stood for. Of course, once my panic subsided, I remembered having learned about NTP (it stands for Network Time Protocol, if you don’t already know) but, since I’d never actually installed and configured it before in the real world, I didn’t really know where to start.
Google gave me what I needed in no time at all and, within no more than ten minutes, my new workstation was happily synced with the outside world. So what kind of resource served my needs on that particular occasion? There’s no competition: the user guide. All I really needed was the name of the installation package:
sudo apt-get install ntp
..and after that, a quick read through the /etc/ntp.conf file told me everything I needed to know about things like servers, pools, and drift. It took a bit more research over the next few days to get me up to speed on the difference between stratum 1 and stratum 2 servers and jitter and insane time, but the initial hands-on experience taught me more than a dozen pages of abstract backgrounders.
Ok. Now if I were to write a chapter on NTP in a Linux administration guide, what should I include? Certainly, I would start with basic installation and configuration that would include setting up an NTP server (which is actually not a difficult task). What else? There’s plenty more on technical topics like jitter and drift that might prove useful some time down the line. And some people will definitely want to know about certain security weaknesses that have been historically associated with NTP. Perhaps it would also be fun and useful to include a guide to building a stratum 1 server using a Raspberry Pi and an old GPS device.
But by this time I will have distracted 90% of my readers from their immediate goals, as they really only need to get NTP up and running. But, on the other hand, leaving out all the more arcane technical details might make it harder for them to reach the kind of level of understanding that will allow them to make smarter decisions in the future. But on the other other hand, can’t they just look that stuff up on line when it becomes necessary?
Three thoughts:
- When designing a technical guide for a specific audience, which will be most efficient? Probably something that’s closer to the how-to-guide end of the spectrum.
- Which might have the best long-term outcomes? More likely the full-service version.
- If I aim to serve the greatest proportion of the population the greatest proportion of the time, which of these will work best?
What do you think?
