A Recipe for Documentation

Imagine opening up a cookbook to a recipe, Introduction to Chocolate Cake, and reading the following description:

Chocolate cake is a delicious desert that, besides being beautiful to look at, has a host of health benefits that will help you live a happier, more full life. And that’s not just us boasting! Chocolate cake is chock full of vitamins, minerals, antioxidants, and more, each of which we can provide hard statistics to show you the importance of.

That sounds great! It sounds like if I want to learn how to make a chocolate cake, this is the recipe to start with! Why would I want to start by making a desert in any other way? Well, under that it says this:

This recipe will be very in-depth, but we will assume you are already an accomplished baker. If you’re not an accomplished baker, maybe consider buying a chocolate cake from the store. You won’t have the control over the recipe, like you came here to learn, but, hey, chocolate cake.

Woah! I thought this was an introduction to chocolate cake! I came here to learn how to make chocolate cake! Why am I expected to be an accomplished baker before I learn how to make chocolate cake?

That question, why am I expected to be an accomplished baker, I think often gets overlooked when writing technical documentation.

This week, I started playing with a big, well-known JavaScript framework. Specifically, because I’m a health (performance) nut, I was trying to figuring out how to do Server Side Rendering (SSR) with it. I know from having looked in to this before with other tools that building applications this way was different than only client rendering. Even though we call them universal applications, the reality isn’t quite that. About 1/2 way through this week, the documentation abruptly changed. It went from a simple set of documentation that I could get running in a handful of lines of code and then expand on, to documentation that assumes a lot of upfront knowledge and doesn’t start running until the end. Well, I say that, but I only assume that. I got to the step that effectively started “we assume you already know how to do this” and stopped to write this post instead of learning a different tool to continue this introduction tutorial.

This is an issue of complexity in our current development ecosystem. Our tools are tightly coupled (complected, if you will) with others. This leads to needing to know a whole complex stack in order to print out <div>Hello World, you're on page {{ url }}</div>. Complexity, in and of itself, isn’t necessarily bad. Assuming that something as complex as our current ecosystem is as easy for the audience as it is for those writing the documentation makes for bad documentation. In fact, it’s a mostly wrong assumption to make. Documentation like tutorials, by and large, are not for individuals who have conquered the complexity presented to them. They are for individuals who are learning these concepts for the first time. The more we write documentation presuming existing expertise, the less useful we make these tutorials for the audience that’s most likely to use them.

That’s not to say there isn’t a time and a place for advanced or expert tutorials that assume a level of expertise. Anything that does, though, shouldn’t be billed as an introduction. In fact, it likely should go out of its way to inform users, in very clear, upfront language, before describing what someone will learn, that this is going to require skills they may not have. If that’s the case, links to learning material should be given, up front, so users can self-pace and not get stuck midway through, lost for where to go next.

Returning to our chocolate cake, how can we write better documentation and tutorials? Well, if you know me, you know the answer: food! Specifically, taking a page out of our cookbooks! I recently got the cookbook Modernist Cuisine at Home, and opening it up was a revelation. Besides the gorgeous photography, they’ve managed to make the highly scientific and technical molecular gastronomy cooking techniques approachable to those new to it! The key to how they do this is two-fold: how they structure the book, and how they structure their recipes. Peep the Modernist Cuisine at Home Brochure to see how they not only describe what may be needed up-front in the book, but show readers how to use equipment they already have, and explains in-depth the new tools they’re introducing. Diving in to the recipe section itself, and we see a model we can follow for our documentation and tutorials. Let’s break it down.

At the very top of their recipes, they set expectations; how much will this make, how long will it take, how to store, how difficult is it, what special requirements are needed, what can this be paired with. Before even looking at the description, I have an idea of what I’m going to need in order to accomplish this recipe. The special requirements section all reference tools they talk about earlier in the book. The description is next, explaining what they like about the recipe and why certain tools are used. Finally, there’s the recipe itself. Each step is broken out with exact needs of each ingredient. If a step has multiple ingredients (unfortunately not pictured there), all of those ingredients are listed on the left. If a set of ingredients has multiple steps, they’re all listed on the right before the next set of ingredients. Steps that describe something a user may not be immediately familiar with include pictures to help guide them. This, then, should be our gold-standard in writing documentation.

Translating this in to our world of technical documentation, we should start by setting expectations clearly up-front. How difficult is this going to be? How long is this going to take? What versions of everything are being used? What knowledge do I need to have before coming in, and where can I learn precisely what I need to know? Next, a description of the actual documentation, and why these tools and techniques are being recommended. Finally, our steps; what are all of the things we’re going to need up-front for the following set of steps. Then the next set. Then the next set. All while avoiding words that assume existing expertise.

Writing documentation’s hard. Automated output never really gives enough for someone to learn from, so we need write long-form text. When we do so, we often, intentionally or not, assume users have the same grasp on the technology being used that we do. By doing this, we wind up writing documentation that’s inaccessible to a large group of people who would like to use it. So let’s improve that. Let’s learn from cookbooks and start thinking about documentation as descriptions of kitchen equipment or cooking techniques, tutorials as recipes. I think that by doing so, we can write documentation as tasty as chocolate cake!