There's a question on the main page, What are the metrics for software documentation?, that is extremely vague, unclear, and overly broad. As it stands currently, I believe it should most likely be closed as not a real question:

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, see the FAQ.

As far as the answers go, do they fully address the question? I'm not 100% sure they do, but that's because the question is vague. The information in the answers is helpful and addresses a problem, and I think both David and Mark Wallace are able to sort of tell what the asker is really asking, so I'm thinking maybe we can fix that with some edits to the question so it's more clear to others.

Remember, maintaining good quality is important to becoming a graduated, productive Stack Exchange Q&A site. So if this particular question has to be closed, so be it, but I'm hoping maybe we can find a way to improve the post instead, as the lessons about wanting to "measure for the sake of measuring" is valuable. Of course, the answer could also be that no editing is required, and that the question is perfect as it is...

What do you think?

3 Answers 3


So I thought a bit how to edit the question and I cannot come up with anything that does not materially change it. What I personally liked about the question is that the question itself exposed the ignorance and lack of knowledge of performance metrics of and in itself. It became more than 'how do you measure performance around a paper deliverable?' So while we can answer the possible ways you can measure paper deliverables, my answer centered more on the deeper issue: the lack of understanding metrics itself. Thoughts??

If I am making this more than it should be, then maybe it deserves a rewrite. I can make an attempt.

Happy Thanksgiving to everyone!

  • Hi David, one of the things our community does really well at is looking deeper into questions like this and putting in a much more comprehensive, thoughtful answer. If I edited it to be specific to the answer, we might lose the "ignorance" aspect of it, and that's a great point. Since a lot of the newer PM's will likely be searching around this same idea, then maybe the answer is that we leave it as is, in its unedited form!
    – jmort253
    Commented Nov 22, 2012 at 18:23
  • I made some edits, including that question you suggested. I'm thinking that, since the original post was a bit unclear, that this makes it clear, yet without losing the "ignorance" aspect of it. I agree that it's more valuable with the "I'm new to PM" feel, so if you think those edits detract from that, we can roll it back. Let me know.
    – jmort253
    Commented Nov 22, 2012 at 18:35

For me, the question isn't vague (like 'How can I manage a project?') It's just simple. As we have lines of code, function points, etc. for code, what are the metrics available to measure documentation? Although no one came with an answer like that, I totally agree with David, more important than the metrics itself is why are you measuring that?

  • 1
    For me, the wording was a bit vague because the asker made a statement instead of asking a question. I think my edits helped clarify the question and make it an actual question, but without losing the "simplicity" aspect of it. I agree simple can be good.
    – jmort253
    Commented Nov 23, 2012 at 0:59
  • Indeed, your edit was very helpful :)
    – eMgz
    Commented Nov 23, 2012 at 15:50

I was wondering: facing this question, why don't we assume that it means something like

"I have a pretty good idea of what I want. Of course I isolated what the main project goals are but I don't know of any metrics that could help me with performance measure regarding these goals. What are the most commonly used metrics (after all I might have missed something obvious that everybody uses)? When to use them? When not to use them? What information do they provide?"

  • I'm not sure the one-size fits all approach would really solve a real problem. Instead, assuming the asker did know what the goals are, he/she should tell us so we can provide answers that fit those goals. What's more, if any future visitors show up with a similar problem, the answers may be more helpful than just a list of the metrics Bob and Sally use on their project. In this case, since the details weren't provided, I'm thinking the answers about the process of finding what metrics to measure are pretty useful. It's like teaching someone to fish vs giving them a fish. :)
    – jmort253
    Commented Dec 9, 2012 at 2:55
  • I also want to say that, if you were the asker in this case, we'd just simply use comments to ask you more questions about your project goals to fill in the missing details. ;) It's definitely not a bad start to a question, assuming the asker is still around.
    – jmort253
    Commented Dec 9, 2012 at 2:58
  • IMO teaching how to fish here would be more like "It all depends on your project goals : if your stakeholders are more interested in foo then you can measure bar which produces a good indicator about foo while being blahblah..." Metaphorically, David's answer alone is more teaching how to make a fly than teaching how to fly-fish : "design your fly according to what the fish eats" instead of "use this fly if your want to lure this fish, and that one is more for that kind of fish" In short this should not prevent us from answering the actual question - I can't ;) Commented Dec 9, 2012 at 10:26

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .