Why a content spec saves you time and money

A content specification will save you troubles, time, and money, especially when you’re not the lone writer on a documentation project. It will ensure that you offer your users consistent and holistic documentation across a team of writers.

A content specification is a list of all topics to be created which ideally maps planned topics to requirements and/or designs to ensure comprehensive and complete documentation. It usually comes in a table with one row per topic, listing:

  • Topic heading and/or file name
  • Topic type (concept, task, reference, or whatever else you may use)
  • Topic owner
  • Writer (in case writers may be different from topic owners)
  • Reviewers (for example, subject-matter experts)
  • Date ready for review or for post-review editing (depending on your workflow)
  • Mapped deliverables (where the topic appears, for example, a certain user manual, the online help, etc.)
  • Time estimate (how long will it take to write the topic, optionally, including review)
  • Documentation task type, to help you estimate time:
    • Create new topic
    • Major rewrite of existing topic
    • Minor fix or addition to existing topic

Without it, you risk delivering a bunch of topics with gaps in some places and overlaps in others. You can still string them together, but no overview topic can convey a coherent content experience, if you didn’t plan for it and bake it into the topics and their structure.

So a content spec is a blueprint of your documentation project, just as you would create one before you start building a house – or design any kind of experience.

Yet content specs often elicit negative reactions…

“Oh, but we’ve managed without one so far…”

Many tech writers I know are very competent, and a few are lucky to boot. Considering all their projects with more than, say, 50 topics which didn’t use a content spec, I’d bet half of them are incoherent (“organically grown” is an oft-used euphemism).

The cost doesn’t stop at poor user experience. Such examples are also more difficult and more expensive to maintain, especially if you have overlapping topics and don’t remember to update both of them…

“Bah, reality eats specs for lunch…”

To an extent, yes. But on the whole, reality is an orderly patron. In my experience, the final documentation reflect the approved content spec in up to 80% of the topics. An average 10% of the topics get added during the writing, where concepts or prerequisite and auxiliary procedures are found missing. Another 10% of the topics get reorganized because the initial content spec misunderstood something, or because content simply makes more sense somewhere else.

“Even if, we’ll fix it later…”

Yes, you can. But once again it’s very expensive. Remember that the list of topics is only one result of the content spec. Their structure is another. Finding that a structure by workflows is inferior to a structure by, say, instrument, requires not just re-ordering topics, but re-writing a lot of them.

You can avoid this by drawing up a complete content spec before you write a single topic and getting it signed off by the key stakeholders, so they know rather well what documentation they will get. The 20% deviations mentioned above are usually justifiable, if they conceivably improve the deliverables.

– Given that content specs are a big help in creating and maintaining efficient and effective user documentation, I strongly recommend using them. If you have any experience with or without content specs, I’d love to hear it.


9 Responses

  1. This approach sounds very waterfall to me. I agree with the goals (make sure the content is complete & consistent) but for writers working in an agile environment such detailed up-front planning would be a waste of time.

    That said, it *might* be worthwhile even in agile shops to maintain a living content spec document for a large feature, and add to it or update it as an artifact of sprint planning. But I think the agile answer would be that the docs themselves serve as the spec.

    We’re looking to implement a “final” review process as part of the last sprint for some large features, to allow us to look more holistically at the completeness & consistency of docs generated over multiple sprints. Besides that, each sprint’s work should build on — and if need be, iterate on — what was written during the preceding sprints.

    • Thanks for your comment, Shane! You’re right, it is rather waterfall-ish, and most of the content specs I’ve used were outside agile environments.

      I don’t have enough first-hand agile experience, so I can only guess that with agile, the user story could possibly replace a content spec?

      On the other hand, I’ve seen some agile shops which don’t maintain user stories – and they sometimes struggle to ensure that their products are presented and described in a holistic way which is meaningful to customers (as opposed to developers or subject-matter experts).

      So I’d be worried that iterative development would organically suggest a structure and taxonomy which might not reflect actual workflows or user tasks. Any ideas about this?

    • Hi Shane,
      this is an interesting discussion! Are you actually doing agile? Do you do it more scrum-ish with sprint planning, story points and burndown charts? Or more kanban-ish with reducing the work-in-progress? It would be great if you could share a little background of your project setup.

      • Chris,

        Where I work, we “SCRUM our Agile”.


        I also agree with Shane Taylor. Agile doesn’t seem to allow for such up-front work.

        I work from tasks (that are related to Stories – the SCRUM part) that have attached “living” functional spec documents that are really just overviews, requirement lists, use case descriptions, and UI info along with other bits of information.

        Working in small three week “sprints” naturally limits the size of a story (or at least that seems to be the academic goal behind it). When I estimate my “story points” (effort) for each story, I take the story information and (yes, most of the time mentally) answer the content spec information you have in this post. This information gets delivered to the Scrum team as an estimate.

  2. Good post, Kai. I’ve found content specs to be useful too, although your 80% “reality” figure sounds a bit high. Perhaps that’s because we write the spec before we have a complete understanding of the audience and their tasks. But that’s actually a good thing: writing (and rewriting) drafts of the content spec helps us build that understanding.

    In terms of project management, I usually do scheduling and estimating at a higher level: chapter or plug-in. Do you find it helpful to plan the topic level? It must take more effort to track the project at that level — do you think the benefits justify the costs?

    • Thanks, Larry, for your spot-on questions!

      I must admit, my 80% reality figure comes from (waterfall) developments where I don’t start my content spec until development is finished and testing is about to start or has started already. Also, I’m lucky enough that I often have requirements specifications and/or designs which describe the audience and their tasks adequately.

      For project management, I find my estimates more reliable on topic level. That doesn’t mean I estimate each topic individually and meticulously. But going over a list of topic titles reminds me of hefty topics and the general amount of “standard topics”. When it comes to tracking and controlling while I write, I actually do lump sections or chapters together.

  3. Hey Kai, great post. I think the guidelines you have can still be applied to writing in an agile environment, just on a smaller more iterative scale. When I have worked in sprints, I have planned out new or updated topics at the start of a two week sprint. I’ve added them as tasks associated with the user stories for that sprint. Since I know what user stories are in the backlog and most likely to be tackled in the next two or three sprints, I have a rough larger scale content plan, but I don’t map out the other topics in any detail until the other sprints start. For larger features, I agree with Shane about adding in a holistic review process towards the end of a series of sprints.

    • Thank you, Diana, for adding an agile perspective on user stories and how they relate to content specs! It seems that they are a very valuable part of agile development, specifically for tech comm, but also to keep the entire development on track.

  4. […] For more info about content specifications, see Kai Weber’s excellent post about it.  […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: