Melanie Spiller & Coloratura Consulting
A Tonic for Ramshackle Wordsmiths
Home
Articles
Blogs
News
Contact
About
Copyright Melanie Spiller 2011. Do not copy without permission.
Home
Articles
Blogs
News
Contact
About
History Lessons

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 is 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 wasn't once 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.