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
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.”
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.
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.
- 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.
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.
- Subject Matter Experts without documentation experience as direct contributors
Antipattern: The Guru
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.
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.
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.
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.
Don’t worry about building a scalable process or sharing knowledge about how the documentation process works.
- 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.