Help us build better doc

by Bill Wear on 17 March 2023

Suppose you have a new feature for your software. Features can come from many sources, internal and external to your organization. Internally, they may originate with marketing, sales, support, developers, executives, or even known issues or prior experience. Externally, they can come from users, customers, and even competitors. In fact, competitors are often the catalyst for revolutionary features.

Features can come from anywhere, even from little things you see while you’re biking in the afternoon, or watching the barista in the coffee shop. These many features get collected into roadmaps, which make their way into development plans and specifications, which get assigned to the many developers that make a product successful.

While there are many developers, though, there are few technical authors to translate all this glory into immortal prose — or at least into a decent how-to guide. In fact, large teams of 20 or 30 developers often depend on just one writer to produce all of their documentation. This seems like an unbalanced workload: many features, many developers, one technical author — and yet, it’s a very common practice.

How can this possibly work?

Well, a lot of teams have tried to make this work with a few gimmicks:

• They try to make the writer better, with training, and bootcamps, and certifications, and lots of special tools and procedures.
• They try to make the text simpler by organizing it better, and being sure never to repeat messages (e.g., use links instead).
• They try to improve productivity with automation, removing everything from the writer’s focus except writing and editing.
• Eventually, they usually try incentives, like a bigger salary, a bigger title, or maybe just a bigger refrigerator.

These all help — especially the refrigerator, if you love diet soda like I do — but they aren’t sufficient to get the level of productivity needed to produce great documentation. So what else can we do?

Hello, crowdsourcing

“Yeah,” you say, in a sort of sarcastic tone, “crowdsourcing. Don’t expect much when you’re crowdsourcing documentation!” Then you share with me your litany of normal expectation:

• Bad quality
• Unpredictable delivery
• Awful narratives
• Developer angst when they have to try to throw doc together, at the last minute, while they’re trying to get the release out the door.

Well, let’s be bold. Let’s suppose that “don’t expect much” is almost the right mantra for this plan. What if we modify that to, “don’t expect too much”?

• Suppose I can accept sentence fragments, like a virtual mind-map of nouns, adjectives, and verbs?
• Suppose I tell my contributors not to worry too much about good grammar, or spelling? (That’s my job).
• Suppose I tell my contributors that narrative cohesion shouldn’t even be on their radar? (That’s my job, too).

You’d probably say, “Uh, sounds nice, but will it even work in practice?”

I think so. Check out this video to find out how.