I previously wrote down a few documentation antipatterns, or descriptions of commonly seen bad solutions to problems. If you’re not quite sure what an antipattern is, it’s explained in that blog post.

I’d like to present a couple more documentation antipatterns to avoid, both drawn from experiences that we’ve had in the past, but have solved along the way.

Antipattern: Big Ball of Mud

Definition

The Big Ball of Mud is a well-known antipattern in software engineering. To quote the authors who coined the term:

“A Big Ball of Mud is a a haphazardly structured, sprawling, sloppy, duct-tape-and-baling-wire, spaghetti-code jungle. These systems show unmistakable signs of unregulated growth, and repeated, expedient repair. Information is shared promiscuously among distant elements of the system, often to the point where nearly all the important information becomes global or duplicated. The overall structure of the system may never have been well defined.”

Motivation

You’ve never documented software before and don’t know where to begin, so your startup begins collecting and adding content. You need something that “just works” for now.

Applicability

You are growing quickly and you are adding content to the documentation as quickly as you can to make sure customers have all the information.

Consequences

  • While you might solve your immediate problem, eventually maintaining everything will be a nightmare.
  • Content that is hard to navigate or unintuitively organized.
  • Content that is inconsistently formatted or stylistically jarring.

Mechanics

Keep fixing problems and adding content as needed without stepping back to look at things at a high-level. Don’t take the time to architect the system, define constraints, and document these systems.

Known Uses

  • Startups
  • Subject Matter Experts without documentation experience as direct contributors

Antipattern: The Guru

Definition

The Guru is the person who controls all the documentation. Everything has to go through The Guru and get his or her blessing before it can be used.

Motivation

A single decision-maker can get things done quickly, and since we’re a scrappy team we don’t have time for design-by-committee.

Applicability

You have a small enough base of content or simple enough product that it’s relatively easy for one person to understand everything that needs to be documented.

Consequences

It’s good job security for the guru, but what’s the backup plan?

There are a lot of other smart people in your organization with knowledge to share and ideas on how to improve the docs experience, but they might not feel empowered to submit changes or suggestions.

Mechanics

Don’t worry about building a scalable process or sharing knowledge about how the documentation process works.

Known Uses

  • Early-stage companies
  • Organizations without successful cross-departmental collaboration

At SendGrid, we solved the Big Ball of Mud problem through our Sustainable Documentation architecture based on Jekyll.

And, now that we’ve got a full-time Docs Developer on the team, more people than ever are helping make the content and structure better. It’s easier than ever to contribute to SendGrid’s open source documentation.



Brandon West
As Director of Developer Relations for SendGrid, Brandon's focus is on empowering developers to build things, gathering feedback for new features and improvements, and fostering a cooperative developer community for anything that needs email integration.