Melanie Spiller and Coloratura Consulting
Copyright 2020 Melanie Spiller. All rights reserved.
History Lessons
Melanie Spiller and Coloratura Consulting
Don’t get me wrong—I LOVE history. Especially medieval history. Super especially medieval musical history.
Triple super especially medieval German musical history. But I don’t think history has any place in technical
writing. Here’s why.
First, define your audience. If your audience is of similar technical expertise to yours, they don’t need the
history because they’ve come down the same path you have. If your audience is beginners, they don’t need a
history lesson because there’s no context for it—all they care about is the product they’re using now and going
forward. The same is true for readers who are looking to improve existing skills; that the product didn’t use to
be as good as it is currently goes without saying—these readers only want to know how to accomplish their
current goals.
Next, look at staying focused. If the subject of your piece is how to develop tight security using Purple People
Plotters, what difference does it make if there used to be gaps of a different nature than there are in this year’s
version?
Finally, look at the purpose of your piece. If it is a marketing piece, pointing out past foibles is not exactly
flattering to your product, even if you are trying to show the manufacturer’s attention to user needs. It’s like
asking your friend when he stopped beating his wife: there is no good answer. If you are writing an instructive
piece, you need to provide context, but I don’t see how history is relevant. I want to know what products I
need to have installed, what languages I need to code in, what limitations there might be, and if there are any
whammies to watch for. In an instructive piece, there is a task to accomplish and I want to get to it right away.
As an editor, I remove (or encourage removal) of history lessons every time. Unless the word count is
significantly under, I just can’t see taking up space with something that isn’t immediately useful.
If you really can’t resist putting in a history lesson, can you do it at the end, like an epilogue? That way, if I’m
really intrigued, I can read on or head for the manufacturer’s archives, but I don’t have to stop developing
unless I need a break.