Amara GrahamI'm really into cooking, baking, pickling, really anything that will end in me eating something delicious. But I didn't find it enjoyable or "get good" at cooking overnight. My parents cooked most of our meals and if you planned on eating said meal, you were required to provide some amount of assistance, regardless of your blood relation to the family.
After graduating out of dorm life I realized I needed to feed myself or starve, so I started getting bolder with my kitchen experiments and I'm pleased to say I'm still alive.
"Ok Amara, but where is the tech components of this blog?"
Hold on, I'm setting up the metaphor.
"Ok fine."
In the Kitchen
If you stand in a kitchen and watch my dad cook - he reads a recipe, studies it, then goes through and pulls out all the things he needs to make it happen. For banana bread he usually has to pull the frozen bananas out early to thaw them enough to peel them, he portions out the spices so he can toss them in while mixing, he sprays the loaf pan before the mixture is together.
If you watched me in my first apartment attempting banana bread for the first time, you would have seen someone who barely read the recipe (I've made this before, with supervision, and watched my dad make it for years, how hard can it be?) and did exactly every step of the instruction in series. Pull frozen bananas out of the freezer, immediately realize you can't peel a banana when its extra frozen, wait just long enough you can pry the peel off, smash the mostly still frozen bananas, slowly add each spice one at a time, measuring as you go, mix everything together, spray the pan, realize the oven isn't on, wait to pre-heat, blah blah blah, why did this take double the prep time?
My dad has always taken the methodical approach to everything, he's a chemist and he loves math. I'm impatient and can't spend even 30 seconds idle when I know I need to complete a task, so I pretty much have the attention span of a Border Collie (have you seen those dogs stare at a ball, full body shaking with excitement?).
At My Desk
I'm sure you'll be shocked to hear when I sit down to learn some kind of new tech, I barely skim the tutorial or docs, immediately start the "doing", and often end up frustrated and annoyed with the experience. In some cases I tell myself things like "oh I've used an API like this before, I can just make it work" and 3 days later I'm banging my head on the keyboard.
"Amara, just slow down and actually read the tutorial."
Easier said than done. Not just for me personally, but for any dev, and that includes your dev coworkers, customers, community, etc. Time is precious, workplaces are more agile than ever, and people pay money for other people to stand in line for them.
In My Brain
Now recipes, just like tutorials, can be poorly written, but even the good ones can suffer from poor execution as I rambled on above.
There are 5 things I learned from getting better at following cooking recipes that I think apply to written technical content.
- Ambiguous Terms
- Jargon
- Chunking
- Brevity
- Audience
Let's take a look at each one.
Ambiguous Terms
Have you ever read a recipe, seen the word "mix" and go... with a spoon? A stand mixer? How long? Or how about "hand mix"? Did you know that a 'Hand Mixer' is an appliance and not the things at the end of your arms? Because a few years ago when we first started dating, my now husband did not.
In tech, we love using the same term for a number of different things. Or we have a number of different words for the same thing. Really friendly to beginners right?
Something like "Run this" might make sense to you, the engineer who built it, because its probably never crossed your mind that you run it globally and not in a particular directory (or vice versa) but that can be one of the most irritating things for a dev struggling with the worry of doing something wrong and/or irreversible.
Be explicit in your use of terms and maybe consider a glossary of terms relevant to your project/product/industry/company. What does this mean in this context, right here, right now? Don't leave your reading punching out to search for answers.
Jargon
Every talk I've given on AI to beginners has included a disclaimer about not only ambiguous terminology but jargon. 'Fine-tuning' is not super intuitive, neither is 'hyperparameter'. 'Fold in' or 'soft peaks' in cooking is right up there too. Mastering the jargon can disrupt retention of fundamental topics.
Explaining these terms early in docs and tutorials is crucial. You should not assume knowledge of jargon, so this is another +1 for a glossary.
Chunking
I am a huge fan of multi-part tutorials and how-to series, so long as they are done right. At the end of each part in a series, you should have a small complete something. Developers may not have time to sit down and do a 3-6 hour tutorial, but they should be able to get 20 minutes to an hour of uninterrupted time.
You don't want to tackle a slow cooker recipe at 5pm expecting to eat it for dinner, but you may want to brown some meat so it is ready to toss in the next morning. If I have 20 minutes today to set myself up for success later today or tomorrow, I need to know I can get it done in the allocated time. And I need to feel like I can pick it up again without rereading the entire thing.
Brevity
Unlike this blog which is probably way too long for most of you, the more concise your written technical content the easier its going to be to follow. It's part of what makes the Tasty videos so appealing to watch - someone makes a sped up, top-down recipe that feels fast and easy even if its neither.
This doesn't mean you can't write an introduction or a conclusion that goes more in depth about the content, but when you get to the meat of the docs or tutorial it should be a lean, mean, executing machine. Food bloggers are great at this, they may give you step-by-step pictures and commentary, but they almost always include the recipe separately. So feel free to tell me how you are going to save the world with this tutorial, but keep it out of the exact steps I'm following so I don't get overwhelmed.
Audience
This is maybe the most important, although I could argue that they all are. Knowing your developer audience is extremely important in technical writing. This helps you make decisions about what languages and references to use, what their workstation may look like, and maybe even things like their attention span.
If your audience is students, whether they will admit it or not, they tend to have WAY more time to sit down and really study a tutorial. Or maybe they are participating in a hackathon and it just needs to work as fast as possible.
But maybe your audience is enterprise developers, like mine often is. This means it has to be production-ready, maintainable, and even trainable across teams. Your maintenance team may be entirely separate from your product engineering team, so the content they follow may need to be different.
Knowing or identifying your audience can be challenging, but this is a great opportunity for your devrel team to really shine.
Celebrate Those Incremental Improvements
Like I mentioned earlier, I didn't wake up one day and realize if I actually read the recipe, prepped ahead of time, and researched how to do certain kitchen techniques (again, ahead of time), I could maximize my time in the kitchen and feel less overwhelmed. In fact, I'm probably 50:50 in my ability to prep and run in parallel or haphazardly skim in series today. But snaps for me because this week I measured everything out before I started cooking!
I'm sure you could make an argument that my dad is a 'senior' in the kitchen and I'm not (but I'm also not junior either), but he'd prefer you only use 'senior' when used in conjunction with "senior discount" at this point in his life. Let's say 'seasoned'. Whether you are a junior or senior dev, you still need the content you are consuming to prepare you for success.
But with more and more folks using services like Blue Apron, Hello Fresh, Home Chef, arguably boxed Bootcamp experiences for the kitchen, we have a new generation of folks training themselves how to follow recipes and we can translate that experience into the tech world, allowing for more confident, empowered folks in the kitchen and at the keyboard.
So instead of shouting "read the docs" or "follow the tutorial" make sure your content is as consumable and delicious as a home cooked meal.
