Do we, as technical writers, tell the reader everything we know? Do we heck!

We most emphatically do not. And listing just the reasons why we do not would take a long time and a lot of words. That’s listing the reasons, not explaining any of them. But let’s talk about one of the reasons.

Readers are busy people. If they read the documentation at all, it’s usually because they were using the product to get something done, and hit a roadblock. They want to read just long enough to get unblocked.

Even if the reader is reading to learn, the technical writer still gets the reader’s attention for a limited period, not an infinite one. So we tell them everything relevant and no more.

Developers are also busy people, and most of them provide information to technical writers without context. “Update the procedure to reflect current functionality.” Uh huh. Have we by any chance assumed that anybody has told the technical writing team about any recent changes? Or have we perhaps assumed that the technical writing team has the ability to use the product?

Some developers are absolute rock stars. Without prompting, they provide a summary of how the product works now plus a quick sketch of how that was different in the past, a brief mention of why the change was made and why the user will care and benefit from the new feature, a link to a document (such as a wiki) with tons of background, and at least a small handful of screen shots.

The whole concept of screen shots is a massive topic for another time. But screen shots provide a way for me to introduce an important point:

I often ask developers for material that’s for me, not the reader. I need to understand what’s going on. I need to see how it works. I’ll consume a lot of information, but I won’t pass it on to the reader unless it’s relevant.

Very, very few developers have ever said to me anything remotely resembling “I gave you what you asked for and you didn’t use it.” I suspect most of them understand the difference between my not using their help and not publishing it. So there’s no pushback in that area.

But occasionally, a couple of times a year at least, a developer will hesitate to provide me with information because the end user shouldn’t have it. My usual reply is to thank them for making sure that I understood the sensitivity of the information. Quite often, I don’t have to say “Now may I have the information anyway?” The developer, once I share the context of my request, sends me the information right away. Their goal was to protect the user (and protect the company), not be a gatekeeper.

This all ties back to a lesson about writing fiction that long predates the availability of the home computer. Some fiction requires research. Historical fiction tends to require the most research. The least artful writers include all their research in their final draft. Sometimes this is just laziness; other times the writer’s motives are more pure. “I was fascinated by this, so I thought I’d share it with you.” Which is fine so long as it doesn’t bring the story to a crashing halt for a history lecture.

So the advice for writing historical fiction and for writing to help the user of a product is the same: Do your research, but don’t burden the reader with everything you learned.

And that’s why we don’t tell everything we know.