I would like to get information about measurements and metrics for documentation work in a project.

The project can be itself limited to documentation as a deliverable or documentation as part of entire product delivery.

How can I measure performance around a paper deliverable?

  • 2
    What's so wrong with this question? I agree that maybe it's not very well formulated, but I can't see how we're helping just down voting it without any explanation.
    – eMgz
    Nov 20, 2012 at 15:55
  • 1
    I agree with eMgz. This question highlights an extremely common issue with performance metrics design, at least in my experience. Nov 20, 2012 at 16:34
  • 2
    @iliya, Welcome to PMSE! There is some confusion around what you are asking. Clarifying the question could help the community provide a better set of answers. For example, do you want to know how much time is generally spent on documentation? What is the context: e.g. are you doing a project and want to know if you are spending too much/not enough time on documentation? Nov 20, 2012 at 17:35
  • Hi @DavidEspina - I created a meta post on this question. In short, since you answered, I'm wondering what you think about editing this question to match the answers better and/or improve it?
    – jmort253
    Nov 22, 2012 at 6:33

5 Answers 5


When anyone asks this question in this way, it implies the desire to measure for the sake of measuring, an end versus a means to an end.

You metrics pop out as a result of decomposing your project goals. Any other measurement that has no parent goal will be looked at by bored stakeholders, who will eventually learn to ignore that report. Goals are decomposed into objectives that are deliverd by plans. The question becomes, how do you know when you get there, how do you know your plan was achieved? The metrics you need answer that question.

  • 3
    I'd add that metrics that align with strategic goals are more likely to be valuable.
    – MCW
    Nov 20, 2012 at 13:28

Sorry for the late answer but I just discovered this forum and joined it.

There are many ways to look at documentation so I have to make some question (and assumption) to limit the field of this discussion.

The first question is: are we talking of end-user's documentation (HTML files, printed manuals, etc.) or developer's documentation (JavaDoc and the similar)? In my answer I will assume we are talking of end user's doc because dev's doc is usually covered by many kinds of Programming Best Practices.

The second question is: are we talking of documentation as a set of (deliverable) documents or as the developement process that produces such documents? In my answer I will assume we are talking of deliverable documents because the dev. process is already covered by the same Best Practice used for software dev.

Given these assumptions, there are at least the following metrics to take into account.

  1. Coverage. Does your documentation cover all of the features/aspects/capabilities of the documented project? This can easily be tracked using a simple database (or even a spreadsheet) listing all the implmented features and the related documents.

  2. Understability/readability. Are the text and images of your docu understable for an average reader? This is sometime measured with a simple read/question&answer test: have a couple of users read your documents and answer a few questions. The "quiz" should contain questions regarding the documentation itself ("What does the docu says about this feature of our product?"), regarding the product features (What does our product do?) and regarding the working of the product (how do you perform this task?).

  3. Conciseness/effectiveness. Does the docu use a reasonably small amount of word and images to communicate its concepts? There are a lot of good text metrics out there but you can reasonably assume that any feature should not require more than two (7 inches diagonal) pages to be illustrated. Each feature-related chapter should contain at least one image or one bullet list to draw attention. Each chapter should be divided in paragraphs and each paragraph should not be longer that 6 - 12 lines. Each phrase should not be longer than 12 -24 words. Long, weird/unusual and hard-to-spell words should be avoided when possible (and clearly defined in a glossary when not possible). Each image should not try to represent more that 5 or 6 objects/concepts/"things".

These concepts are typical of the software development industry but can be easily applicated to many other fields (mainly mechanical, automotive, aerospace, electronics and so on).

Of course, documentation is an interactive process (we document our product and you, user, read our documents and tell us if you understand them). The only way to have a really good documentation is to keep the communication channel open. Have a forum on the web, answer the user's question and collect the best Q&As in a well orgainized, well written FAQ. Publish a collection of articles on the most interesting topics and bugs (a public "knowledge base").

  • Hi Alex, sorry for the late welcome to PMSE! Thank you for posting a great first answer! :)
    – jmort253
    Dec 13, 2012 at 6:51

(Concur with everything that @David Espina said). Are you writing the quality management plan for your project? If the project is effectively to produce a document, then the "metrics" are really your quality goals.

  1. How does this document support the organization's strategic goals?
    The project metrics should demonstrate this alignment?
  2. How will the document relate to business case? The metrics should demonstrate that the document fulfills the business case.
  3. Who is the consumer of the document? How will they judge the utility of the document? Does it need to be read by people of a given reading level? Does it need to be comprehensive measured against some set of criteria?

There is a management philosophy that says that if you can't measure it, perhaps you shouldn't be doing it. I'm not sure I subscribe to that, but the corollary1 makes some sense: if there is a purpose in doing it, you can probably measure it.

In this case, and I am speculating here, you could do something simple like compare word count with documents from similar projects. More ambitiously, how about submitting a 360 degree feedback survey to your document's audience. Many ISPs and shrink-wrap software vendors ask "How helpful was this?" on every online help page.

Alex Bottoni's answer mentions conciseness and readability. These too can be measured. I won't repeat Alex's measures but I will add this. If your document is in English and will be published, or your employer or client is a member of the Plain English Campaign(PEC), you might choose to apply for the PEC Crystal Mark.

There are also the FOG score and Flesch test.



If the docs are online, you could even measure how often they are read.

Don't forget that word count and reading frequency should inversely correlate to how intuitive or self-documenting your software is (and that applies both to end user software and to APIs.) So, though a need for hefty documentation might reflect the complexity of your problem domain, it is also a warning sign.

1: more properly I should have said contrapositive


K at Eight to Late offered a fairly comprehensive answer to the quality question in the blog post What is good?.

I'm not sure that I agree with K - I'm more inclined to believe that Quality is conformance to the requirements under discussion, but the entire post struck me as applicable to your question.

  • Hi Mark, is there anything from the blog post that you'd be comfortable citing in your answer in a quote block? I think it would enhance your post for readers to see the highlights and then decide if they want to visit the link. Hope this helps! :)
    – jmort253
    Dec 13, 2012 at 6:54
  • I tried @jmort253, I tried. Unfortunately everything I picked up as a potential quote block required extensive discussion. The relevance to the OP's question is in the whole, rather than in any identifiable part. Point taken though.
    – MCW
    Dec 13, 2012 at 11:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.