TC Myths

All technical communication myths in place.

No one reads technical docs

Users prefer to try and experiment with a product rather than refer to its documentation. As a result, documentation is not required to ship the product.

Background

Anuradha (14 Technical Writing Misconceptions That You Should Know!) lists this as a reason that’s used to skip the documentation as a way to catch up to a deadline. She also lists some of the consequences of such an approach, such as customers reporting problems whe the product does not behave as the documentaiton describes it should. This is presented more as an appeal to common sense and cites no research.

Pratt (Nine myths about technical writing) suggests testing that assertion by reviewing the analytics.

Houser (Myths, Fallacies, and Lies in Technical Communication) claims this has been taken out of context and, in his presentation, refers to a blog post by Joel Spoolsky that starts out saying, “When you design user interfaces, it’s a good idea to keep two principles in mind: 1. Users don’t have the manual, and if they did, they wouldn’t read it. 2. In fact, users can’t read anything, and if they could, they wouldn’t want to.” So, you should design your product as though people don’t/won’t read. Houser then cites another article Study: Rumors of Written-Word Death Greatly Exaggerated that shows reading is not on the decline, just that the sources of reading content have changed over the years.

Prakash (Technical Writing: 10 Myths and Facts (Part 1)) asserts that documentation is a requirement by appealing to common sense; however, cites no research.

This myth could also be derived from research that suggests people, in general, don’t read on the web. The People read on the web article at UX Myths lists several articles that describe how web-site visitors tend to not read the content verbatim. However, that doesn’t say they never read the content. Instead, the references cited in People read on the web describe many different types of reading styles from reading word for word to varios types of skimming and scanning methods.

Brandt et al. (2009) studied how software developers interacted with technical documentation to perform programming tasks and noted that they interacted with the documentation intermittently to obtain details that they did not remember. They observed that “Programmers deliberately choose not to remember complicated syntax. Instead, they use the Web as external memory that can be accessed as needed.”

This is a specific example of a more general observation that information is generally only read on the web when it’s necessary to accomplish a task and then it’s only read until readers believe they know what they need to know (Redish, 2012).

Another aspect of this myth has to do with long-tail content whose use is difficult to predict, by definition. In fact such content might never be read. However, this type of content can be extremely valuable to the reader when it is accessed (or not; it’s hard to know in advance). Reference content is a good example of long-tail technical documentation. This myth asserts (usually with some data) that many or most reference topics will not be read or will be read very rarely. The logical fallicy of this argument is that it generalizes “most” to “all” to conclude that no on reads technical docs.

Survival tips

  • Understand the content’s use-cases as seen from the user’s perspective and then verify that understanding with research and analytics.
  • Remember that research conducted on one type of web content, such as content written to attact clicks, might not apply to technical documentation, content intended to help or instruct, because the audiences have different motivations and contexts.

Mentions

References