Do Repeat Yourself

Good documentation requires different rules than good engineering

Most programmers I know are familiar with the idiom “Don’t Repeat Yourself;” and it’s a critical lesson for software engineers. Any algorithm worth doing right is worth doing right once. When you copy and paste a good bit of code, the copies can diverge; and when two supposedly identical algorithms no longer match you get obscure and impossible errors.

Yet when writing documentation, or comments, engineers often misapply the “don’t repeat yourself” or DRY principle. I’ve regularly heard statements such as, “Comments aren’t necessary, the code is readable alone;” or “Don’t say this again here, just link to the other page.”

I’m here to argue that it’s okay to repeat yourself when writing documentation. I know this is counterintuitive, but repetition is a key pattern in documentation. Let’s explore why.

Documentation can be memorable

Repetition is okay because it helps you remember important material. A fun example comes from an episode of the Simpsons, Lemon of Troy, where Marge delivers a brief speech including the following quote:

Marge: Bart, you have roots in this town and you ought to show respect for it. This town is a part of us all. A part of us all. A part of us all! Sorry to repeat myself, but it will help you remember.

It’s true! Teachers know that saying the same thing multiple times helps a listener build a relationship with the material. It’s the same reason why studying your notes can help you to master a topic, and why students who have shared study groups to talk about their subject score better than students who don’t hold such discussions.

I recall vividly a driver’s education class I took when I was getting my first learner’s permit. The teacher had the entire class repeat, three times, out loud, all of the core rules in the book — and that kind of repetition helped us all score 100% on the written tests.

Different engineers require different documentation

Repetition is okay because programmers use lots of different types of documentation. A typical developer relations program will produce reference material that explains how each component works; how-to documents that explain how to solve common problems; and blogs and webinars covering special topics of interest.

If your developer relations program tackles all of these things, your bloggers and writers will inevitably repeat themselves. When I wrote Avalara’s developer relations site I found myself writing the same ideas three times on three different pages — reference material, howtos, and blogs.

Each time I wrote down the idea, it was similar but not an exact copy. Let’s look at a basic example:

• Reference Page: “CompanyID: The company ID is a number that uniquely identifies this company.”
• Howto: “When your create API call succeeds, the server assigns you a company ID number which uniquely identifies the company.”
• Blogs: “Make sure to write down your company ID number —if you have multiple companies, this number will uniquely identify each one.”

As an author, I felt that I was rewriting the same text over and over. But this kind of repetition is necessary, because a programmer won’t see all three.

A programmer who sees a company ID field mentioned and wants to know whether it is a string or an integer will read the reference page. A programmer who has been tasked with learning your system will read the howto. And a casual visitor might skim the blog posts to see clues as to how your system works.

Skimming and comprehension

Repetition is okay because programmers don’t like to read documentation. Nobody wants to have to master the quirks of your image processing library! They just want to find the answer to the problem they have right now.

Programmers skim documentation, and repetition helps increase the chance they’ll find the right idea. A distracted reader needs help to really absorb your material. This brings to mind my eighth grade English teacher’s instructions for writing a book report:

• In the introduction, tell everyone what you’re about to say.
• In the body, tell everyone what you have to say.
• In the conclusion, remind everyone what you just told them.

Why was this advice so valuable? A reader or listener will try to engage with you, but many things can distract them. Staying focused is a challenge. Even momentary interruptions can derail a speech or article; repetition helps a reader or listener to reconnect to the main thread of discussion afterwards.

The writer and the reader have different experiences

I recall thinking to myself, one day when I was writing a blog post, “Haven’t I said this before? I should delete it. I don’t need to say this same thing again.”

But I was making a mistake. I was remembering what I had said during a presentation at a conference, and I was writing a blog post for a different audience. I, as a writer, had experienced this same sentence many times; but for each audience it had been new.

As a writer, I learned early on to avoid repetition within a single article or project; but as a person who writes many articles and gives many speeches, I am going to feel repetitive because I’m doing the same thing many times for different audiences.

The challenge at hand is to always focus on the reader or listener, and to give yourself permission to feel a little bit repetitive. Your audience deserves to hear your whole story, even if they might have heard part of it before.

After reading this article, I know that you might still disagree with me. You might be saying to yourself, “I despise repetitive documentation; there’s no way I’d support this approach.”

But I’m going to keep on with it, because I’ve learned something interesting: repetition is a form of practice. When I try to explain something for the fifth or sixth time I’ll often be writing the same sentence from memory, and I might find a slightly better way to phrase it.

Or I might realize some important distinction that I didn’t mention before.

Or I might see that something I said is wrong.

Or see a way I could make the code more intuitive.

My goal, as always, is to write something useful. For me, this type of practice allows me to refine my documentation and hone my writing skills. And part of it means that I have to become comfortable with — at least a little bit — of repetition.

This article is adapted from a talk I gave at APIs and IPAs meetup in Seattle in 2018