8 Responses to Three components of content organization

  1. Neal Kaplan 2014/08/12 at 18:59 #

    This is a great summary of things that have been bothering me for years.

    “The problem this poses for writers is that they are more familiar with classification, and their tools are built more for classification, than they are for stickiness and relationships. This needs to change.”

    Writers trying to force content into a tidy classification scheme end up creating unusable documentation. I’ve seen this firsthand when readers complained that I didn’t document something important, and it was two or three steps away from their current location on the TOC. But of course I built that TOC, I knew it inside and out, and most readers never looked at the darned thing. My customers searched for some keyword or phrase, the search gave them a likely option, and when they didn’t find what they wanted they tried again (usually a minority), gave up (far too many), or complained (not nearly enough). In any case, they blamed me (or my company) for not giving they what they expected.

    The problem was that the relationships were incomplete, stickiness was all wrong, and I was relying on classification to make it work. The result: Upset customers and a massive overhaul of the documentation.

    • Mark Baker 2014/08/12 at 21:44 #

      Thanks for the comment, Neal.

      Indeed, it seems to be a complaint as old as the hills in tech comm: the user was close, but they never found the content. So many of the times that users complain about missing information, it isn’t actually missing. They just couldn’t find it because the docs were not designed to support the information finding strategies that the user were actually using.

      • Neal Kaplan 2014/08/12 at 23:36 #

        It’s almost amusing: we’ve been expecting the users to learn how to use the documentation so they can learn how to use the product!

        • Vinish Garg 2014/08/13 at 21:07 #

          Neal, interesting little comment there. I remember that a few technology books have an small section as ‘How to use this book’. Although the book has a TOC, a preface and an introduction, this ‘How to use this book’ section prepares users for what to expect, where, and for what kind of information.

          Is it time to embrace the same for product knowledge base? When I plan a new KB, I plan it as if I would plan a new product, a KB itself is a product and I often have a section as ‘How to use this KB’.

          I understand that users refer to a KB when stuck, when they are short of time, and this ‘How to use this KB’ may not make sense to them; however it helps them when they are not able to find what exactly they are looking for (assuming that it may happen with any user, anytime). Two, this section certainly helps those users who are trying to know the product in general, such as new features, upcoming release, whey they are evaluating a product (they have more time to refer to support), and when they are comparing multiple products to make a buying decision.


          • Mark Baker 2014/08/14 at 08:36 #

            Thanks for the comment, Vinish.

            I hate to say it, but, by and large, if the reader has to read how to use a knowledge base, they won’t use it.

            It is something of an axiom of content strategy that if the reader has to learn how to navigate your site, you have already failed. And I think this is particularly true for technical communication. After all, people come to knowledge bases, and to tech comm in general, because they are struggling with a problem they cannot solve. Their brain is full of the problem. They have no mental reserve to devote to learning the navigation. They are frustrated by their problem. They are not in a mood to learn something new.

            The last thing tech comm should do is further tax the reader’s mental or emotional resources by requiring them to learn to use the docs. Instead, it should work the way the reader already expects it to work. And if we take full advantage of all three means of organizing content, then the ordinary Web conventions of search, link, scroll, and back provide all the navigational tools we need to organize any content set.

            The cardinal rules of information design should be familiarity, simplicity, and consistency.

  2. Vinish Garg 2014/08/15 at 20:27 #

    Thanks Mark. To be honest, I saw it coming from you. 🙂

    There are systems where the architecture is complex, the workflow is too inter-woven and so planning the IA for their KB can be tricky. For example see the SalesForce help at: https://help.salesforce.com/apex/HTHome and I am lost. It does not make much sense to me, neither for structure nor for layout (layout, refer to your post on staging your content few weeks back).

    For such cases, I am happy to defy the conventional wisdom “The cardinal rules of information design should be familiarity, simplicity, and consistency”, if a quick note on ‘How to use the KB’ can make things easier for users. The only objective of this section is to give quick less-than-a-minute directions to users.

    We may conclude that such a ‘How to use this KB’ section helps us cover up the actually poor architecture of KB. Not necessarily. As I said, the product is bootstrapped funded and cannot really afford six-ten months’ budget for its KB and redesigning and restructure for a complex KB (such as of SF) may have its own challenges and limitations. Till the time it happens, why not to help users use ‘whatever the KB they have’ more effectively. Conventional wisdom and best practices are understandable but like a cop, an occasional barge into no-entry is fine with me to catch hold of a nasty element! 🙂

    PS: I posted a reply 2 days back too, guess it landed in your SPAM.

    • Mark Baker 2014/08/19 at 07:27 #

      Well, certainly, if you are stuck with the KB and your users are having trouble using it, it can’t hurt to provide information on how to use it. I doubt it will get read much, and I doubt it will help much (though it may, for some audiences) but if it is all you can do, you should certainly do it.

      The fact of most of our lives is that we have to make do with what we have most of the time. The opportunities to make major changes only come along every so often.

      A big part of the problem, though, is that the systems we have, and, often, the systems that we adopt when we throw out the systems we have now, are ones that rely on complex classification schemes to address problems that could be addressed much more simply by stickiness and relationships.

      When it comes to tools, tech comm is drowning in complexity, and it holds us back from keeping up with our user’s real information seeking behavior. We need a simpler approach. But simple here does not just mean less, it means different. That is what the SPFE project is trying to introduce.

      But until that door opens for us, yes, we have to make do with what we have.


  1. Tech Writer This Week for August 14, 2014 | TechWhirl - 2014/08/14

    […] Three components of content organization […]