Pretty hurts: Why better trumps best


What are the characteristics of a great documentation set? Completeness? Accuracy? Style? Format? No! A great documentation set is one that meets its objectives, and sometimes the barrier to greatness is not dedication, skill, or passion, but a reluctance to let things go. Every document we publish should reach a certain quality threshold - but that threshold varies depending on its audience, the maturity of the project, and the overall project goals. What matters is not that docs are perfect, but that they are good enough.

But how to determine if a doc is "good enough"? This talk will cover how to:

  • Define document quality
  • Establish an appropriate quality bar for a document or doc set
  • Determine if a document meets that bar.

We're all overloaded. We're all stretched for time. Every hour we spend making a doc better than it needs to be is an hour stolen from other projects where we could have more impact. Choosing "good enough" doesn't mean we're lowering our standards; it means we're choosing appropriate standards and prioritizing correctly. Don't let the perfect be the enemy of the good.

  • Conference: Write the Docs EU
  • Year: 2016

About the speaker

Riona MacNamara