Mikhail Ostrogorskij, 2008
Theses of Report at Documentation Today Conference, 2008.
One of the most painful questions that developers are faced with is estimation and justification of time required for technical documentation development. In case of failure to meet the term time, a developer assumes the moral, official and sometimes financial responsibility. It makes no difference, whether the term was put forward by the developer or imposed on the developer by a customer or manager. Therefore, documentation developers need a methodology to provide a more or less precise and, most importantly, well-grounded estimation of documentation development time, already at the problem definition stage.
Before we speak of estimation, we need to make a few reservations as to planning as such.
First of all, the time required to develop a package of technical documentation mainly depends on the labour content of the task. This is not true in every situation (in the situation of baobab growing it is probably not true at all) but it works for documentation.
Secondly, any work runs various risks–illness, urgent travels, delays in related works, etc.
Thirdly, even if the developer is concentrated on one problem, which is a rare case, he still spends some time (usually around 25%) on meetings, reporting, training, support of earlier projects and other routine.
That is why here, we will assume that it is labour content that documentation time is calculated by, and will focus on the ways of labour content estimation in working hours per worker. Having measured the labour content, we can set the term time through a planning procedure considering resources and risks. The procedure is described in books on project management and is not specific for documentation.
Published methods of time estimation in documentation
Methods of time estimating for technical documentation exist already and are even described in standards. For instance, ISO/IEC 15910-2002 offers two methods: top-down design and minutes/hours based design.
Top-down method suggests a problem be divided into parts (documents, chapters), each part measured in pages, and further planning based on a certain documentation output ratio. The authors of the standard believe, in particular, that a writer monthly produces 22 pages of new text and 44 of updated. Although this ratio may seem ridiculously low at the first glance, the fact is that it includes not simply written but already approved pages that have gone through the entire cycle the standard stipulates. Besides, the writer will only be doing the proper writing seven days a month at most, which, given the daily output at 3-4 pages (as most agree), gives us about the same result. (This is described in detail in the documentation management seminar.)
Minutes/hours based method determines the output ratios for each activity involved in the documentation process. Thus, if we are to write a 100-pages document, we will spend X much time on typing, Y much time on editing, Z much time on graphic design, etc.
The ‘Read Me 1st’ method by Sun describes a similar technique.
Although one may trust or distrust the said methods, they have one thing in common–they are based on the number of pages in the documentation. This substantially diminishes their value, as documentation process, unlike translation or page layout, implies that the work volume can not be known in advance.
Software engineering is faced with this problem as well. On the one hand, software development time must be estimated. The work load on one programmer is measured in SLOC (Source Lines of Code); the coding time ratios are also defined. Yet, no particular task implies the exact program size in lines. Therefore, estimating the time and labour content (the reservations made for documentation process remain true with programming) of a particular development uses techniques based on the so called metrics of a task. This term describes any measurable features of a task.
The ‘Use-Case Points’ method regards features of system usage cases as metrics. Points are added for each actor and each use case, depending on their complexity by a certain scale. For each project, Technical Complexity Factor and Environmental Factor are calculated. The summed points and the two Factors are then inserted in a special formula to calculate the task complexity in UCP’s. Although each company may have its own ratio for converting UCP to man-hours (it is set when the method is first introduced), it is believed to lie within a certain range when work is properly organized.
The Functional Points method is similar, except the metrics are more definite: the number of screen forms, database entities and etc.
To estimate labour content of technical documentation, we need to develop a method combining the strong points of metrics-based methods and the minutes/hours based method.
There is probably no need to dwell on the point that documentation problems may be different, and thus, metric sets should also be different. Here, for the sake of definiteness and clearness, we will study one of the most common types, namely, development of user guidance for application software with graphical user interface. As metrics we will use:
Project Metrics
User Perspective Metrics
Data Metrics
User Interface Metrics
We offer to single out the following activities:
Product Studying
Documentation Plan Development
Writing
Text Approval
Text Drawing-up
Author believes this list to be quite realistic, yet it is to be regarded provisory at this stage of the method development, and may be amended.
Labour content of a task is calculated as follows. For a particular task, we measure values of all listed metrics. For each activity, labour content is calculated by the formula:
Labour content i = Metric1*Ti1 + Metric2*Ti2 +…+ MetricN*TiN.
For this purpose, Tij coefficients form a rectangular matrix sized M x N, where M is the number of metrics, and N is the number of activities.
Total labour content equals the sum of (or weighted sum of, as in the more flexible variant of the method) labour contents of all the activities.
What now stands between us and a fully operational method is lack of adjusted metric lists and an adjusted conversion table. Again, we now consider only one type of documentation tasks, while actually several such types are required for the method development. Receiving such results requires a larger experimental material and can only be accomplished in coordinated work of many professional society members.
Planned Activities in this Direction:
You are welcome to send you suggestions to the author: misha@philosoft.ru.