4 Common Antipatterns to Avoid in Your Documentation

Design patterns are powerful things. They help us short-circuit a lot of trial and error by relying on the past experience of others. They provide a common lexicon for communicating complex concepts. And, applied thoughtfully, design patterns improve our understanding of our craft as well as its effectiveness.

And you’ll notice I haven’t mentioned software. Design patterns exist for many disciplines, and the core concept originated in architecture. One of my personal favorite pattern languages comes from the book Presentation Patterns, and it describes common solutions for problems encountered when preparing for and delivering technical presentations to audiences. Teachers also often use pedagogical patterns.

What Is An Antipattern?

Just as patterns are good solutions to common problems, antipatterns are bad solutions to those problems. They are solutions that are derived from a novice understanding of a problem domain, and that lack of deep understanding causes the solutions to be ineffective at best and harmful at worst.

Some of the documentation antipatterns below may be familiar to you if you are a software developer. That’s because I believe a solid approach to documentation is to treat it like software.

To describe the antipatterns, I’ve borrowed the same format used in Presentation Patterns, which is in turn derived from the “Gang of Four” descriptions in the book Design Patterns.

Antipattern: Forgetting the Past

Definition
Can you easily tell what the documentation looked like a year ago? Can you revert a page or several pages back to that state without too much effort? Documentation that lacks a history causes problems.

Motivation
It’s really quick to set up a wiki or a WordPress site and start editing away at content without worrying too much about the platform. That’s super agile and means we won’t have to waste time reinventing any wheels!

Applicability
Any time you need to get something off the ground quickly, it’s usually easier to pick something that has less than ideal change tracking and version control.

Consequences
You’ve jumped right in to building content, but you’ll have a difficult time knowing who made which edits to what documents, and when. Reverting sections of the documentation back to a previous state will be difficult, and prototyping new pages or features will be very difficult.

Mechanics
Start using a wiki or WordPress with their default lack of backups and less than ideal version control.

Known Uses
Early-stage startups
Young open-source projects

Antipattern: Sad Kid On Show and Tell Day

Definition
I’m crying because I have this really awesome widget but I left it at home on the counter. Instead of showing it to you, I’ll just have to talk about it and you’ll have to take my word for it.

Motivation
It’s really hard to convey the essence of a thing without being able to see it and play with it, but I can tell you about some of the superficial characteristics that are easy to describe.

Applicability
Any time you are dealing with an abstract concept and don’t have the time to create a concrete implementation of it to use as an example, just describe the mundane details of the abstraction and hope the reader can figure it out from there.

Consequences
You’ve done your job of “documenting” the thing, but the audience has a fuzzy conception of what you are talking about and it doesn’t seem nearly as cool to them as it does to you.

Mechanics
Don’t describe any use cases or real-world examples or provide any sample implementations. It’s that easy!

Known Uses
Organizations with no dedicated docs person or editors.
Engineers who think the implementations are obvious.
Writers who are unfamiliar with the product.

Antipattern: Echoes

Definition
Little bits of information that are repeated and/or mutated across several documents, rather than stated once and referenced.

Motivation
You want to be sure that readers have everything they need to know within easy reach. Copying and pasting is easy.

Applicability
If you have a large amount of content, it might be easier to repeat some content so the reader doesn’t have to go look for it somewhere else.

Consequences
Readers will have all of the information they could possibly need in one place, but they might be wondering why some concept from another part of the documentation is showing up again somewhere that seems tangentially related.

Mechanics
When you think a piece of information might be relevant in the context of something else, copy and paste it there, or paraphrase it slightly.

Known Uses
Reactions to a single customer complaint.
A well-intentioned person trying to be very thorough.
When the search function doesn’t work well.

Antipattern: Dependency Hell

Definition
Yeah, you know this one. That one rubygem that depends on an old version of a different gem and you have code that depends on a newer version of that same gem and then you fall down the hole of making it all play nicely.

In documentation, however, it can also be assets like that handy screenshot of a third-party tool, or a link to some other company’s documentation.

Motivation
Screenshots are an easy way to convey a complex action to a user, and your interface has many complex actions. There are also some things that are relevant to a user but are better served by being linked.

Applicability
Your product integrates with many other products, or you are documenting your user interface.

Consequences
You have a bunch of pretty screenshots and contextually relevant links, but now you have elements in your documentation over which you have no change control flow. Those links could 404 or the third-party UI could change and make your screenshot obsolete.

Mechanics
Liberally sprinkle screenshots throughout the documentation without implementing any way to make sure they stay up to date. Add a bunch of third-party links without a link checker.

Known Uses
Software with overly complex user interfaces that need explanation.
Software that integrates with many third-parties.

Now that you’ve seen these four common antipatterns, you can hopefully avoid them in your own documentation.

For more on how we’ve approached these issues, find out why we open sourced our documentation last year and how it helps us avoid some common antipatterns.