Embedded Files
PERSPECTIVES
On expertise, invisible complexity, and learning to
I used to proofread digital magazines by reading one line forward and the next backward.
It wasn't a particularly good way to enjoy an article, but enjoying the article wasn't the point. I was checking publications that had been converted from print to digital formats, and I needed to catch errors that ordinary reading made easy to miss.
When we read for meaning, our brains are remarkably accommodating. We recognize familiar words, anticipate what comes next, and occasionally supply what we expect to find rather than what's actually on the page. This is wonderful for getting through a novel; less so when we're supposed to notice that something went wrong during conversion.
Reading backward interrupted that process. I could concentrate on individual words, their spelling, and their appearance without getting distracted by the story.
I had other tricks, too. I'd scan pages for unusually short paragraphs that might indicate an accidental line break, or suspiciously long ones where a break might have disappeared. Neither was necessarily an error, but an unexpected pattern gave me a reason to investigate.
Years later, I found myself doing something remarkably similar while auditing software documentation. I wasn't looking for misspelled words anymore. I was looking for signs that the instructions, or the processes behind them, had become more complicated than anyone realized.
And once again, sometimes the most useful thing I could do was stop reading.
The trouble with knowing too much
The trouble with knowing too much
One of the great advantages of being a technical writer who's new to a product is not knowing what we're doing.
Not at first, anyway.
We don't know the product's terminology, its peculiar workflows, or the historical reasons behind its more baffling design decisions. We ask why a field has a particular name, why a task requires navigating three different screens, or what an instruction means when it tells users to configure the appropriate settings.
These are useful questions. They're also questions that experienced employees may have stopped asking years ago.
At first, we don't have to imagine what it's like to be a new user. We are one. Then something happens: we learn the product.
We become familiar with the workflows, understand the exceptions, and recognize problems that once required considerable investigation. We can anticipate questions, explain complicated behavior, and work more independently of the subject matter experts who initially taught us.
All of this makes us better at our jobs. But it also takes us further from the experience we once shared with new users.
Expertise doesn't just give us more knowledge. It changes what we pay attention to. Familiar actions become automatic, unfamiliar jargon becomes ordinary vocabulary, and complicated decisions collapse into what feels like a single obvious step.
An experienced user might say, "Just update the configuration." They know which configuration, where to find it, what needs changing, and how to recognize whether the change worked. A novice knows none of those things.
After a few years with the product, however, we may no longer recognize how much information is concealed inside that little word "just." Novices know they're missing information. The trouble with expertise is that we can become so accustomed to filling in the gaps ourselves that we stop noticing the gaps are there.
When the page starts telling on itself
When the page starts telling on itself
At Kibo and LibreDigital, our knowledge content used outlined callouts in various colors to distinguish different kinds of information and levels of urgency. These were useful for readers. A warning stood out from a general note, and important qualifications were easier to recognize while following a procedure.
But those same visual conventions gave me another way to evaluate the documentation.
During audits, I'd sometimes scan an article before reading it closely. If the page was crowded with callouts, I flagged it for further investigation. I did the same with procedures containing deeply nested numbered or bulleted lists.
Sometimes I'd literally squint at the page until the words blurred. The text became harder to distinguish, but the larger shapes of paragraphs, lists, and callouts remained visible. Without the words competing for my attention, I could get a clearer picture of the document's overall structure.
Reading without reading: an approximation of what I saw when I squinted at a page to examine its structure rather than its words.
The visual clutter was a signal, not a diagnosis. One callout might explain an unusual exception, while another might warn about a legitimate risk. But when an article needed constant qualifications, I wanted to know why.
Was the information poorly organized? Had the article accumulated years of additions without being reconsidered as a whole? Were the exceptions unavoidable? Or had the product itself become unnecessarily difficult to use?
The shape of the page couldn't answer those questions. It could, however, tell me where to start asking them.
This was something I emphasized when mentoring other writers. If a procedure kept accumulating notes, caveats, and special conditions, it was worth discussing the underlying workflow with Product rather than automatically adding another explanation.
The same principle applies to interface design. Tooltips can be helpful, but when nearly every control requires one, it's worth asking whether the interface is communicating enough on its own.
Not every complicated procedure is evidence of bad design. Some tasks genuinely require complicated decisions, and some warnings are essential. The challenge is recognizing the difference between complexity inherent to the task and complexity introduced by the system.
Documentation can make both easier to see.
Death by a thousand perfectly reasonable edits
Death by a thousand perfectly reasonable edits
Documentation rarely becomes complicated all at once.
A feature changes, so we add a note. A new configuration introduces an exception, so we add a conditional step. Support identifies a recurring mistake, so we add a warning. A later release changes the behavior again, but only for certain customers, so another qualification appears.
Each addition makes sense at the time. Each may even improve the accuracy of the article. Eventually, though, what began as a straightforward procedure has become a maze of exceptions, warnings, and instructions about which instructions to follow.
The article becomes a record of every compromise made along the way.
And because those compromises arrived gradually, the people most familiar with the product may barely notice them. They know why the exceptions exist, which warnings apply to which situations, and how to navigate the workflow without consciously considering every decision.
The documentation reflects that accumulated knowledge, but the reader encounters all of it at once.
This creates an uncomfortable possibility for technical writers: the better we become at explaining a complicated process, the easier we may make it for everyone else to accept that complexity as inevitable.
We can organize exceptions into elegant tables, add decision trees and troubleshooting sections, and use beautifully formatted callouts to make an awkward workflow considerably easier to understand.
Those are valuable skills. But sometimes the better question isn't how to explain the process. It's why the process needs so much explanation in the first place.
The fine art of squinting
The fine art of squinting
The difficulty with expertise is that we can't simply set it aside. Once we understand a product, we can't reliably recreate the experience of encountering it for the first time. We know the terminology, recognize the patterns, and understand what the interface is trying to tell us, even when it isn't doing a particularly good job of telling anyone else.
Telling experienced writers to "just think like a beginner" sounds reasonable, but it doesn't give us much to work with. I think it's more useful to find ways to challenge what familiarity has taught us to overlook.
My visual audits were one approach. By deliberately making the words harder to read, I could see the overall structure more clearly. It was a simple way to interrupt the familiar act of reading and notice patterns I might otherwise overlook.
Of course, squinting only gets us so far. Other sources of evidence can be just as revealing.
Support tickets show where people repeatedly encounter trouble. Search analytics reveal the language readers actually use, which may bear little resemblance to the terminology preferred by the product team. Searches that return no results can expose missing information, but they can also expose a mismatch between how experts categorize a subject and how users understand it.
Watching someone attempt a task can be even more illuminating. A person hesitates over a label that seems perfectly clear to us, looks for a setting somewhere we wouldn't think to search, or makes a reasonable choice that produces an unexpected result.
Questions from new employees deserve attention, too, particularly when the immediate response is, "Oh, that's just how it works."
None of these observations automatically identifies the problem. A confusing article might need rewriting, a repeated support question might indicate a missing explanation, and a complicated workflow might be unavoidable. Or the problem might be the product itself.
The point is to investigate rather than assume.
Technical writers occupy an interesting position between the people who build a product and the people who use it. We need enough expertise to understand the system accurately, but we also need to recognize where that understanding differs from the reader's. Our work can reveal gaps in the documentation, problems with the design, or assumptions so deeply ingrained that nobody remembers making them.
We can't unlearn what we know, and we shouldn't want to. Expertise is what allows us to recognize problems, understand their causes, and explain complicated systems accurately. But it also changes what we notice, which means we need deliberate ways to interrupt the familiar patterns.
Sometimes that means watching someone unfamiliar with the product attempt a task. Sometimes it means examining the questions people ask rather than the answers we've already written.
And sometimes it means looking at a page without reading a word.
_____________________________________________________________________________________
More from Perspectives
More from Perspectives
Google Sites
Report abuse