Skip to content

Writing exercise

A square US Postage stamp with a rendering of a solar eclipse.

As a developer advocate for LaunchDarkly, I need to understand the product in a bunch of different ways – at a technical level to give summaries of how to make integrations work, at a business level to explain how feature flags can save time and money, and at a rhetorical level, so I can quickly gauge my audience and explain it to them in the most efficient way possible. Usually when I start a new project, I’m elbow-deep in documenting how it works and I have to work backward to why people want it to work one way or another. But this time I have the luxury of learning why a product adds value first.

I wanted to make sure I was grasping it, and as my friend Laura’s dad use to say to doctoral chemistry candidates, “If you can’t explain it to this ten-year old, you need to go back and work on it until you understand it yourself.” There is an apocryphal Einstein quote to the same effect. I think the modern version of making sure you really understand something by explaining it derives from Randall Munroe’s brilliant XKCD comic, Up Goer Five. Theo Sanderson built a little text editor with a linter that rejects all the words you can’t use, which is, um, almost all the words. But if you can conceptualize something really clearly, you may be able to describe it with the extremely constrained set of words. Here is my attempt to do so for feature flags:

Computers think in lines. Sometimes we want computers to think in a new line, but it’s hard to change lines all at once. We have to build the new line before we can change to it.

When we build the new line, we give it a cool name and hide it from the computer thinking. When we are ready, we change to the new line and lose the old one. The computer thinks the new line with the cool name is the only line. We can make the computer think with the cool name line or the old line any time. Cool/old, back and forward, when we want.

Sometimes, we want only some people to see the cool-name line. We put them in a cool-name group. Every time the computer gives them a thing, they get the cool-name thing from the cool-name line. Other people still get the thing from the old line. Who is happier? Cool-name group or old-line group?

We try to keep our computers happy and not too busy. Sometimes a new line of thinking takes more work for computers. Instead of making all the computers think the new line at once, which makes them slow and sad, we only tell some of the computers to think the new line. Then we add more and more computers thinking the new line, a few at a time. Soon, all the computers are thinking the new line, but none of them got too busy.

When we are finished with the old line, we make it go away. Now cool-name line doesn’t need a cool name anymore, it is just Line. We change its name to Line. When we want to write a new cool-line, we start over!

I’d love to see the results of some of you explaining your product using a thousand words. It’s not really useful as a way to explain things to people, since we want to teach customers our words and tune our language to their needs, but it’s very useful to show us if we understand something.

Heidi Waterhouse

Heidi is a mercenary technical writer and travelling salesperson of better process and product thinking. She loves writing herself out of a job and teaching people to save themselves from future pain.

Upcoming appearances

Full Stack Conference London
DevOpsDays Minneapolis
Write/Speak/Code
DevOpsDays Chicago
Texas Scalability Summit
Velocity Berlin

Scroll To Top