October 27^th, 2008

My friend came up with a formula for figuring out why Developers always seem to underestimate the time required to develop their software. So then I got to thinking about how to allocate Documentation resources to a project. There must be some metric out there that I can use to figure out how much time my writers need to document software tasks. A quick Internet search proves that there are, but they are surprisingly vague and ... well, usually wrong in practice.

So I thought I'd try to come up with something based on my own observations. This is what the wise folks at work call a WAG (wild-assed guess):

Days to complete (D) is calculated by adding together three factors:

• Time to write (W), expressed as the fraction (T / R)
• Time to bug fix (F)
• Time to information gather (G)

So here is the full "formula":

Calculating W (or T / R)

Time to write (W) is further calculated by dividing the "base" writing time (T), by the percentage quality of the requirements (R).

T is the easiest to calculate; it's based on the idea that, with decent requirements, a writer can write the documentation for five software tasks per day (tasks are defined as 7 steps or less and the related concept material for that task—larger tasks are either broken down into smaller chunks or given more weight). R is a percentage of the completeness of the requirements. The best requirements in the world rate 100% (R = 1), so T / R is equal to T. The less complete the requirements, the larger T / R becomes (so 20% complete requirements means a factor of 5T, etc.)

Calculating F

F = W for new content, F = W / 2 for revised content. It also requires QA time to look for bugs, but that's not my purview.

Calculating G

G is the hardest to calculate. It depends on the number of developers, but not in a simple relationship. This is the least mathematical of them all. If there is one developer, then getting his or her time is virtually impossible, so in that case, G = 2T, unless we are being aggressive and have the ear of the Dev Manager or Director of R&D, in which case it is G = T. If there are 2 devs, then G = T. But after that things get very new-age-ish. If there are several developers, then I have to figure out which of them is going to be amenable to devoting feature hand-off time to dev (and QA). If there is one, then G = T, but if that person is junior or not somehow in the loop, then G = 1.5T. If the writer is new in the company, if the developers have formed a clique or they all go paintballing or rock-climbing together, then G = 2T or 3T or whatever I get from my gut feeling about their availability to the writers (and QA).

Maybe this somewhat tongue-in-cheek table will help to figure out what factor to use for G:

Value for G	Controlling factor	Comments
2T	Single developer, no senior management support for Tech Docs	One developer has no time to "waste" talking to QA, Tech Docs, or Support
T	Single developer, mandate from senior manager(s) to support Tech Docs	When feature hand-off becomes the Critical Path, usually the result of bad docs resulting in customer complaints
T	Two developers	Assumes that one developer can spare the time and knows what he/she is doing
T	More than two developers, loosely affiliated	Assumes that one developer can spare the time and knows what he/she is doing
1.5T	More than two developers, but a junior developer is allocated to helping QA, Tech Docs, etc.	Junior developers can ask questions to senior developers—a luxury the Tech Docs team may not be allowed
2T to 5T	Multiple developers on team, all part of clique	If the writer is familiar and friendly with the developers, use the lower number. If it is a new writer, or a junior writer, use higher numbers.

Here is the response from my friend about these numbers (he knows a lot more about mathematics than I do):

The other factor I'd add (or insert into G) is the time it takes to absorb the new feature into the working habits of the user, so that the documentation ends up being more than just explaining the feature on its own terms. But many tech writers don't bother with that extra step.

Of course, if one had good requirements, use-cases etc., that absorption would be much faster.

Of course :-)

I welcome any and all other comments about this metric; I'd love to hone it to as close to perfection as possible.

---

Read more rants - - Comment on this rant - Email me

---