Now that we’ve published a few ITcookbook recipes, our formula is out there for people to see and use, and love.
Or, uh … not love. I asked a few sysadmin colleagues what they thought of the recipes published so far. Some of them liked the format; some, not so much. Which is fine by me; we need healthy criticism at least as much as we need praise. It helps us improve!
But I have to admit being personally pretty invested in our new format, which to the best of my knowledge, you won’t find anywhere else – at least not for free.
The typical online howto document is text with a few screenshots thrown in. Several colleagues told me they were more comfortable with that format. I found myself being a little defensive of the ITcookbook way. Now don’t get me wrong: text-and-screenshots is a fine format. It gets the job done in many cases. I’ve produced my fair share of text-and-screenshot tutorials in the past. But I think it can be improved upon, and that’s what ITcookbook is about.
Using the Cookbook
Let me show you how I envision someone using ITcookbook. Go ahead and watch; this video literally takes only a minute:
- All of our videos are silent, so they will not disturb your co-workers. But most are captioned, so you know what we want you to see. (Sorry, the one in this article is not captioned.)
- A key takeaway here is that you don’t have to watch the whole video. In fact we don’t even want you to watch the whole video! We know you’re busy, and you’ve got better things to do than watch us blabber away about things you already know.
- Instead, what we recommend is that you use the point-by-point instructions, just as you would a normal text-and-screenshot document. You can easily skim to the part you need.
- But when you come to a point you are not clear on, simply note the timestamp, move the slider to that spot, and watch a few seconds of video.
- If you need to, you can enlarge the screen for greater detail, or remove the captions if they are getting in the way.
- You can also pause the video at any point, which yields the equivalent of a screenshot.
Now each recipe is straight to the point: how to do the task, and very little else. So you can get right to work with minimum distraction. But if you want more background, theory, discussion and so on, we’ve provided that too. Just click the link in the recipe instructions:
… and you’ll be taken to a page where we give more links and our expanded thoughts on the matter.
Serendipity
I’ve already noted that those timestamped caption files, which are then reformatted into the recipe instructions, are a huge time sink. But I think they’re worth it. Not only do they let you easily move to the pertinent parts of the video, they also provide a convenient set of labels. If you want to show a colleague how to setup auditing policies in Windows, just tell him to go to that recipe and read the parts from 02:38 to 05:10.
On another note, a frequent problem I’ve noticed with the screenshot method of documentation is that the reader doesn’t have any context for the screenshot illustration. How does he get to that exact screen? What should he have done before bringing up that screen? What should he do afterwards? Where exactly should he make changes within the screen as shown? What did it look like before changes were made? These things are often far from crystal-clear. With our videos, that’s not the case – the reader can always see all of the context. He can see every step that led up to the dialog, every step involved in responding to it, and all that came afterwards.
Wishes
A few of my colleagues expressed a desire to have every timestamp in the text part of the recipe be clickable. You’d click, and the video would go immediately to that timestamp and begin playing. I wanted that too, and have looked into it, but I’ve found no way to do that for the video on the same page. The YouTube player does have a way to start the video at different points, but apparently only at page load. I judged a page reload at every click to be too distracting, and gave up on the idea.
Additionally I’ve tried to make the video default to showing captions. I’ve tried to set them that way via YouTube’s embedded player parameters; so far it doesn’t seem to be working right. It’s probably a failure on my part. I’ll look into this some more; if you’ve got advice, it’s more than welcome.
Feedback Welcome. Please!
HOWTO sites are nothing new, really. But we’re adding a slightly new twist to the idea, with our carefully indexed/timestamped videos. This takes some folks out of their comfort zones, as I’ve already found.
We’d love to hear your feedback, even if it’s (constructively!) negative. We do ask, however, that it not be a knee-jerk response. Take a moment to at least skim one of the recipes given, and think about the points made above. And then, love it, hate it, or indifferent shrug, let us know, via the comments link below. We have more recipes in the pipe, and your feedback can improve their presentation.
Thanks!