A web log from the irreverent, slightly fishy world of Herb Bowie
It is hard to talk about documentation without addressing the subject of templates: some set of skeleton documents that you can use as a starting point for the Great American Specification that you will be writing as part of your next project.
No writer likes the shock of seeing a completely blank page in front of them, so it would seem that templates would be universally acknowledged as a good thing. However, templates have been taking a lot of heat lately from a number of different quarters.
Here’s a few words from Joel Spolsky on the subject, from his 2004 opus, Joel On Software:
Avoid the temptation to make a standard template for specs. …if you have templates, what tends to happen is that you add a bunch of sections to the template for things that you think are important for every feature. As these sections accumulate, the template gets pretty large. The trouble with such a large template is that it scares people away from writing specs because it looks like such a daunting task.
A spec is a document that you want people to read. In that way, it is no different than an essay in The New Yorker or a college paper. Have you ever heard of a professor passing out templates for students to write their college papers? Have you ever read two good essays that could be fit into a template? Just drop the idea.
Author Tom DeMarco and company even went so far as to excoriate template users in the title of their 2008 book Adrenaline Junkies and Template Zombies: Understanding Patterns of Project Behavior, elaborating in their text that:
When you find a project team that is focused on producing a standard document rather than on considering the content of that document, then you are in the land of the template zombies.
In the land of the template zombies, form takes precedence. It is not necessary to think about the content of the document. It is not really necessary to think at all. The important thing is to have something—anything—under each of the prescribed headings. Not surprisingly, template zombies are adept in the art of cutting and pasting and ignoring anything that does not fit the dictates of the template.
Now, in a research paper just published on March 20 of 2009, Forrester is jumping on the bandwagon, provocatively asking the question, “Are Your Project Teams Living in ‘Template Hell?’” Their paper, primarily authored by Mary Gerush, goes on to say that templates can be useful, but cautions readers to keep the following points in mind:
- Factor in your consumers’ preferences, as different audiences have different needs.
- Remember that diverse project types benefit from flexibility in required deliverables.
- Be consistent where it makes sense, but value flexibility over rigor.
- Keep it simple: value quality over quantity and simplicity over comprehensiveness.
- Improve your templates over time.
In my own personal experience, some of the completed templates I have read over the years have caused me to suspect that their authors must have taken career advice similar to that offered to Mike in the 1936 mystery by Michael Innes, Death at the President’s Lodging:
“And your remarks on the text,” Mr. Gott declared, “are merely a muddle.”
“Yes, Gott,” said Mike meekly.
“You must just keep to the cackle and write nicely. You write very nicely.”
“Yes,” said Mike, dubiously.
“Keep off thinking things out, and you’ll do well. In fact, you’ll go far.”
My own personal advice is that it is often better start writing a document without any template, so that you can focus completely on the message: what is it that needs to be said, and how best to say it?
Once you feel comfortable with your naked text sprawled out in front of you, then go ahead and dress it in the latest template fashion, using the skeleton format there to perhaps prompt you to think of some important areas that you neglected in your original draft.
I suspect that you’re much more likely to end up with a document that someone will actually read if you address it in this fashion, rather than starting your composition as a fill-in-the-blanks exercise.
May 11, 2009
Next: The Progress Polarity