Welcome to TechWhirl Forums

Sign in or Register to get involved in our discussions.

Users’ Advocate: Nobody Reads Documentation | TechWhirl

TechWhirl WebsiteTechWhirl Website United StatesPosts: 396 admin

imageUsers’ Advocate: Nobody Reads Documentation | TechWhirl

The Users' Advocate says nobody reads documentation. So how do we create usable technical content? Design for web, search, consultation, and conversation.

Read the full story here


  • You've summed it up nicely.

    Yes, users seek information and we need to design technical communication to accommodate this information-seeking behavior.
    But to know how to design technical communication, we need to in depth understand the information-seeking behavior of users. We know that users seek, but not how. So, my conclusion is that both the academic field and practitioners lacks this knowledge.

    My academic research is aiming to bridging this gap by describing information-seeking behaviors: When does an information need arise, why and what type of information need arises and how do users go about satisfying the need? A lot of research shows that humans first consult another human, that is, we ask a colleague in person. So the web is most often not the first information source choice.

    My conclusion so far is that the information need of users is generally formalized as questions. Thus, we can talk about question types as I elaborate on here: http://excosoft.com/types-questions-users-ask/. I like your EPPO approach, but my main concern is that we need to know what type of information users search for, to know what EPPO topics to write.

    Why not define EPPO topic type templates based on question types? That is, and EPPO type topic may for example answer "How do I do X?", What is the result of task X", "What does Y, Z mean?" etc. But, I argue that a topic should not be to long as I elaborate on here: http://excosoft.com/should-answer-user-question-short-or-long-topic/
  • mbakeranalectambakeranalecta CanadaPosts: 53
    Thanks for the comment, Jonatan.

    I'm not sure that I agree that we don't know how users seek information. Information foraging theory seems to me to have a lot of value. True, the answer it presents may not be a very satisfactory one for those who are looking for ways to perfect information finding systems. The idea that people are snuffling about trying to pick up an information scent while expending as little intellectual energy as possible does not give much scope for elaborate navigation schemes. But it does seem to do an excellent job of explaining how actual information seeking works -- and why its success rate is often so poor.

    It also seems to be entirely consistent with John Carroll's work and the paradox of sensemaking that he described -- essentially that our current worldview gets in the way or our ability to use and follow information that is inconsistent with that worldview, and that only rough experience -- not superior organization of content -- can get us over that hump.

    Which is also to say that all information finding is local -- it starts from a particular problem and a particular set of presumptions and misconceptions about that problem and its possible solutions. Part of the problem with thinking of topics as answers to questions is that people often do not search for their question, but for what they imagine the answer to be. We could reasonably say that all information finding starts actually starts not with a question but with a guess -- and that guess is usually wrong.

    Getting from a wrong guess to a right answer is an inherently chaotic process. We can't predict the route someone will take as they make their way from wrong guess to right answer. This is why I advocate for a bottom-up information architecture. We don't know where people will start, where they are going, or how they will get there. Our job is not to lay out a path for them -- because we can't. Our job is to make it easier for them to follow their own nose -- because that is what they will actually do.
  • Interesting discussion.
    When you speak of search rank, your are assuming that the docs are visible to the Web, and searched from there.
    And search rank would mostly come from pertinent links into the doc.
    If the user is looking at the doc already, the situation is different - now they need a way to find their answer within that doc.Personally, I always used TOC/Index as a way of locating the info within the doc. A good Index helps me figure out what terms are used in the doc, since they're often called something other than what I expect.

    Presuming you have an in-doc search of some sort, in place of (or in addition to) TOC and Index, this suggests that each topic should have a list of keywords at the beginning, and see-also entries as well. This might be less needed if you have a search engine as smart as Google doing the parsing and proposing synonyms.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    Thanks for the comment, Jay.

    When I first took over the Users Advocate column I stated my basic premise for all that was to follow: that the audience has moved to the Web and if we want to remain relevant we have to follow them there: http://techwhirl.com/users-advocate-where-have-all-users-gone/

    And while this may not be entirely true for every reader -- yet -- it is true for more and more of them every day. The reasons are several, and I devote an entire chapter of my book (http://everypageispageone.com/the-book/) to discussing them, so I won't repeat them here. But a big part of it is that in-book searches suck. It may seem paradoxical, but searching Google works much better than searching an individual work. The reason is that search is a statistical function and Google sees more content and more searches than any local search can ever see. In other words, the local search will never be as smart as Google, not because the algorithm is any less smart, but because it just has so much less data to go on. (http://everypageispageone.com/2011/10/12/the-best-place-to-find-a-needle-is-a-haystack/)

    That said, I agree entirely with your conclusion about how content should be written -- regardless of whether it is visible on the web or not: it should clearly establish its context and it should provide rich links to related subject to help people find what they are really looking for when search does not get them there the first time. More on that here: http://everypageispageone.com/2011/06/25/findability-the-last-mile/
  • This is a pragmatic way to look at technical documentation. I like that you're taking a middle-ground and acknowledging that documentation is necessary and useful but also that documentation is just a means to an end and it should be unobtrusive and efficient.

    I'm learning about XML and the DITA framework right now, and it seems like these tools are optimized for the web and for searches. E.g. with the rules of DITA, you have to break content into topics. And each topic is divided into background information and then the actual steps of the task. Organizing information as standalone chunks makes finding the info you need easier, and I'm sure that it improves search engine results too.

    XML and DITA seem to be increasingly popular tools for tech writers, so it's encouraging that these tools align with the philosophy explained in this article.
Sign In or Register to comment.