Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.

Information Micro-Architecture: Grammar, Syntax, and Cognitive Rhetoric

by Rory Tanner (15 minute talk)

Our discipline is acquainted with the challenges of taking a large chunk of information and making it usable. We know about the basic work of information architecture: categories, structures, hierarchies, etc.

The polar bear book by O’Reilly, Information Architecture: For the web and beyond is a book most of us have read.

In short, we are comfortable with information architecture at a higher level. Rory believes that great things can happen when these principles are applied at a lower level.

Last year, his employer, Shopify, published statistics that surprised him. He found out that users of his docs spent decades of time, in aggregate, reading the docs. This quantity of time reminded him of long running computer programs. Do we have a performance problem? Is the documentation’s “code” sub-optimal for the human brain?

Language == Brain Code

How does reading work?

Put very simply, syntax is really important and ambiguity slows down processing time. If syntax is important and ambiguity is a blocker, what patterns, information micro-architectures, are important.


He provided some simple examples focused on conditionals.

If you need help, read the docs.

There are two parts to this sentence, the condition and the outcome. This can be initially and partially processed as a series of verbs. This is a temporary ambiguity.

Adding “then”, as in “If you need help, then read the docs.” allows the brain to unambiguously read the sentence.

If you need help, read the docs or call support.

Again, this has a very small, temporary ambiguity. Again, though, this could be, in this case three, elements in a series. Again, adding “then” eases the cognitive workload.

If you use single quotes, double quotes or ampersands inside your product tags, grouped filtering will not work as expected.

The user is going to have temporary ambiguity after the first comma and start to try to make the next phrase the outcome or “then.” This ambiguity remains unresolved for a large part of the sentence because the potential series also includes a large amount of parallel phrasing.

In this example, putting in “then” before “grouped filtering” can eliminate some but not all the ambiguity. Rewriting the sentence would really be helpful.

Thinking About Testing.

Using a concordance tool he and his colleagues found the page with the most “ifs.” Then they did A/B testing to see if adding “thens” changed reader engagement.

Reader engagement was chosen as they believed that reduced cognitive load would cause readers to be more likely to click through the page. They have sufficient energy left over to do more work.

Across four tests they saw a small improvement that showed an upward trend. The results flirted with, or potentially were in a serious relationship with, statistical insignificance. However, at scale this could still be useful. Adding additional refactoring after considering the micro-information architecture could really move the dial.

The goal of this talk isn’t to say “use then.” Instead the goal is to get you to think about how the human brain processes. Using this knowledge we can recognize that even at the sentence level, we need to think about how to optimize the “code” for use on the human brain.