Estimating your writing efforts and deadlines is difficult, but essential.
Can you reliably estimate the time you need to write documentation? And the date when you can deliver? It often seems a daunting task because it depends on many external factors:
- The quality of specifications and designs.
- The availability of the finished product.
- The accessibility of subject-matter experts.
- The punctuality and diligence of reviewers.
It also seems futile to spend time estimating efforts when you know you don’t have enough time anyway. But even though it’s difficult and takes time, I recommend that you do it.
If you don’t do it, someone else will make assumptions about your schedule. Even if you’re just left with the ever decreasing time between delayed development and scheduled shipment.
Estimating makes documentation accountable, in both senses of the word:
- You can explain the time you will spend on documentation. So it allows you to plan and budget the time. Share the estimates with your manager, and you can also share responsibility for the efforts.
- You can also be held accountable for the time you have spent. With estimates, you only will have to justify the specific difference that you ran over the plan. That’s much better than arguing about the complete time which may “seem kind of long” to your manager, though you know “that’s just how long documentation takes”…
Estimating makes documentation more transparent, in other words. It gives you and other stakeholders specific numbers to talk about ahead of time. It gives everybody more control over the documentation process.
For example, I once faced the complaint from product managers that documentation held everything up, that we could ship sooner, if only the tech writer got his act together. By introducing estimates and refining the reporting, I was able to show that it was specifically the reviewers which held up the process. Everybody took the estimated time, more or less, but reviewers delayed their tasks unduly. In fact, one late reviewer was a product manager who had voiced the complaint…
What to estimate?
You get what you measure and estimate. Or in the words of Tom DeMarco: “You can’t control what you can’t measure.”
If you count the number of features, options and buttons and base your estimate on that, you’ll get a thorough description of the user interface. And a customer who says, “Don’t tell me how it works, tell me how to use it.”
Apply task-oriented writing and estimate topics, instead:
- Look at the specifications and designs to understand what’s being developed or produced from a user’s point of view.
- Distill or translate what you find:
- Identify modular concepts that users will need to know. A microwave convection combination oven can use descriptions of both concepts with their principles and different use cases.
- Sketch out user workflows to set up and operate the product and break them down into individual procedures. That oven’s manual will probably have procedures to set it up, to thaw frozen food, to heat food (using the microwave), to bake stuff (using the convection), and to clean it.
A high-level view of the topics and their complexity allows you to make a rough estimate how long you’ll need to create useful topic-based documentation.
How to estimate?
Estimate efficiently. I once estimated a one-month project so well, I was off by two hours in the end. The problem was that it took me two days to crunch all the numbers… I can’t recommend that.
So don’t try to be 100% accurate in your estimate, if it takes you a long time to do it. Here are a few ideas to spend less time on estimates:
- Look at past efforts: Most likely, you’ll do some reporting anyway. Use this as the basis for future estimates. Maybe you’ll find an average time you take to write a concept topic. And one time period for easy and short procedures and another for more complex ones.
- Refine your estimates and average sizes over time: No need to get it perfectly right the first time, especially, if you start estimations on your own account. Try to run the numbers beneath the radar before you come forth with them.
- Trust the law of averages: What extra time you need for one topic, you’ll probably save on another.
- Trust your experience: After a while, you won’t need to sketch out individual topics. You’ll be able to take an adequate measure from looking through the spec or design.
To learn more, check out:
- Donald LeVie’s Intercom article “Documentation Metrics”, available via EServer
- Steven Jong’s STC paper “Measuring Quality”, available as PDF
- Gretchen Hargis, et al., “Task-Oriented Writing for Techies“
- Wikipedia on software metrics which has the Tom DeMarco quote
Do you estimate your efforts ahead of time? Is it worth the extra effort? How do you use the numbers to your advantage? Please leave a comment.