Book Review: Accelerate

Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology OrganizationsAccelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations by Nicole Forsgren
My rating: 5 of 5 stars

This book is an excellent summation of the overall findings of the State of DevOps reports and what the implications are for organizations trying to persuade themselves into DevOps transformation.

When I was reading it, I realized that it was everything you would learn if you went to a couple dozen DevOps days and listened to all the transformation stories, and it can be summarized as:

Go faster, be safer.

This is such a counterintuitive thing to say, but I have an analogy for you: When you are trying to teach a kid to ride a bike, they’re like “You’re hurling me at the asphalt and yelling at me to GO FASTER?!?!”. You know, even though they don’t that they will be safer if they go faster, but they feel like it’s very dangerous. Increasing your release cadence feels like that – someone you trust is telling you to do it faster, but it’s very scary to change your thinking about ASPHALT.

Forsgren, Humble, and Kim unpack the scientific analysis of why it works that way, but I find it really compelling to look at the correlation of speed, psychological safety, and business value.

Part 2 of the book is a very wonky, nerdy analysis of the academic methods, which gives the rest a lot of validity, but I give you permission to skip it if you would just like to take their word for it that the math is sound.

Part 3 is a case study of a company currently practicing a lot of the principles mentioned in the book. It may not be relevant to everyone, but it was a nice unpacking of how it could work.

Read if:
You are trying to convince your organization to become more devops-y, or if you want to understand what the benefit of that would be. Also if you would like some eyebrow-massive correlation numbers to use in arguments.

Skip if:
You will only pine because you can’t do this kind of transformation.

Also read:
The Phoenix Project
The DevOps Handbook

View all my reviews

2017 Speaking Recap

This was the year that I got more organized as a speaker. I took up Airtable as a way to track all of my conference proposals, and so I actually have a record of everything I submitted.

Summary

  • Attended 27 conferences, spoke at 24
  • Spoke at 3 user groups, 2 podcasts, 1 video interview, 1 twitch stream
  • 14 unique talks, in a variety of configurations
  • Learned to use Twine as a presentation tool, how to give demos on an ipad over lunch, how to change from saying “I’m a technical writer” to “I’m a developer advocate”

Portrait of a white woman with pink hair, wearing a black and white dress and grinning at the camera

Longer version

Continue reading

The Cardinal Virtues? of Technical Writing

First, a disclaimer: Medium served me this article, but it’s a year old. Weird. Nonetheless, I have things to say about the content.

The Virtues of Technical Writing, by a pseudonymous writer

Introduction

They are gleaned from a Bachelor of Science degree in Scientific and Technical Communication from the University of Minnesota’s Writing Studies Department, years of on-the-job experience, and lifelong self-guided study of the art and science of literacy. I share them here hoping only to bring further communicative light to the world. Heed them and prosper in all of your professional writing endeavors.

Coupled with the woodcut used to illustrate this article, this is exactly the kind of authority-derived advice that makes me gnashy. It’s all about sactioned knowledge and not the dirty fingernails of actually mucking with problems. I believe this person does do the mucking, but they’re not sharing that experience here.

In my experience (but lack of tech writing degree), software technical writing is a lot more like the pratfalls and triumphs of parenthood than any kind of art and science. Every child is generally similar in that they need food, love, and structure. Every child is vastly unique in how, why, and when they need those things. Software products are the same way.

Consistency

I’m not going to argue with this one. Consistency absolutely does matter, because anything else requires extra cognitive work from the reader. It’s our job to make their lives as frictionless as possible.

Thoroughness

always include a near over-abundance of information. Repetition and informational reconnoitering may feel redundant, but the confidence your readers gain from full insight into every step of the process will more than make up for the longer document.

No.

Let me repeat that.

No.

The more you make people read to get to what they need, the more likely they are to drop out. This approach addresses the needs of the long end of the tail over the vast majority of software users who are just trying to get this thing done so they can move on with their day. You need your documentation to be as short as possible while still covering the majority of scenarios. If you get questions or Stack Overflow notifications on some point you haven’t covered, then there is an audience for it, but otherwise, it’s probably just data for the sake of data.

Clarity

I’m also not going to argue this in the abstract, but I’m a little dubious about the absolute nature of assuming that removing words adds clarity. I’m currently editing a piece where the technical writers not only removed adjectives and adverbs, but also a bunch of definite articles. This is not actually useful, as it makes sentences a puzzle and not a seamless transfer of information.

My fourth grade teacher told me that the nouns and verbs are the muscles and bones of a sentence, and the adverbs and adjectives are fat. That’s a good way to think about it. Sometimes, a sentence needs a little plushness, a little padding, something to break up all the angular strength of what you’re saying. If each sentence is a perfect exact crystal, it’s like eating nothing but boneless skinless chicken breasts.

On the bright side, this is the first time that the user’s needs have appeared! So that’s a plus.

Hierarchical structure

The methods, style, and order of your hierarchical structure must first be universalized and then obeyed in every document if the implications of their design are to be understood by readers.

If your hierarchical style is not self-explanatory from the bottom level, you’re doing it wrong. Also, as I’ve been saying since 2012, very few people come to documents as documents. Instead, we encounter them as search results, and not all of the headings in the world are going to save your user if they can’t get what they need from the result returned to them.

We are not writing documents anymore, we are writing topics that are strung together. This is what Corilla is based on, this is what Madcap Flare and RoboHelp and every other modern writing tool that I can think of is based on. That’s because the basic unit of software documentation is no longer the document, or the man page, or the readme, it’s the answer. If your heading does not tell someone what question you are answering in the topic, be prepared to watch your bounce rate exceed your stick rate.

Introductory paragraphs

Agreed. Let’s not just plop some steps down without context. But you know what else you need? Next Steps. Now that you’ve done this thing, what are your increased options, your next configuration task, your results? If someone doesn’t know what they’ve done, can you really say they’ve done it?

Images and screenshots

Uuuuugh. No. Well, not a universal no. I agree that conceptual drawings can and should be used for multi-step processes. These images should be editable and have text labels that overlay the image if possible.

Here’s why we should NOT put images and screenshots in technical documentation.

  1. They are hideous to localize. You are adding thousands of dollars to a project when you do that, depending on your localization preparation and thoroughness.
  2. They are inaccessible. More people than you think are using screen readers, or their monitors cranked way up so the fonts are the size of fingerprints. Every time you say, “use the configuration settings from this screenshot”, a tiny exclusion demon gets its trident and stabs someone with low vision. Don’t do it.
  3. They change. It’s not that I haven’t tried to keep up with my developers, it’s that those charming individuals will move entire interface sections without telling anyone. The thing that is worse than not having a picture is having a WRONG picture.
  4. It’s 2016. We don’t need to show pictures of the screen because the odds are the user is looking at the help and the product on the same screen. Adding an image just gives you a recursive nightmare of non-flowing images next to the thing they’re describing.

Spelling, grammar, and punctuation

Fair enough, as long as you don’t fetishize them. Meaning is more important than form, every time. Sometimes I use sentence fragments for effect. Is that incorrect grammar? Sure. Is it effective at communicating my meaning? Absolutely, to English speakers.

If you find yourself convoluting to try to figure out how to comply with a grammar rule, the solution may not be to rewrite the sentence again, but just to tie a knot and go on.

I do care about punctuation consistency, especially around bulleted lists, but mostly that’s about the voice of the documentation, not The Rules.

Review and revision

I started writing this rebuttal at about 3. I expect I’ll publish it before 5. I expect I’ll iterate it.

Much like my developers, presenting a flawless product will get in the way of me presenting any kind of product at all. I have a system for tracking bugs in my documentation, and I fix and release. That’s all I can do. My review is essentially the same as an intergration test — does it compile, does everything in the package make it in, do I have any breaking errors? Beyond that, I would rather you had something now.


What’s missing

Where’s the user? Where in this whole system of virtues is the person we are supposed to be technically communicating with? When the user appears, they are an empty vessel, to be filled with information (Thoroughness, Introductory paragraphs, Images and screenshots) or running a race for understanding (Clarity).

As a technical communicator, my primary goal is to help people get things done.  If we can design software better so they don’t have to read docs, I have succeeded. If we can make docs shorter or more nimble so they can do their work, I have succeded.

My value is not in writing. That is merely a manifestation of my real value, which is empathic, meaningful connections that allow people to get on with their lives, while incidentally using our software. My value is as much reflecting users back at the developers as it is reflecting the software into the user’s context.

I appreciate that this person wrote up their thoughts, and as you can see, I agree with many of their points, but overall, I think an emphasis on technique over understanding is an easy, tragic mistake.

I could speak with the tongues of humans and angels, but if I have not love, I am but a noisy gong.

1 Corinthians  13:1