I spend most of my time at work thinking about the product users. Those are the people who will be reading what I wrote. That means I spend a lot of time considering what each person might not know, and might not know they don’t know. Part of the job of a technical writer is helping people learn. Which puts me in a very different head space than a lot of the people I work with.

Decades ago now, I worked with a software engineer named Matthew, who everyone liked because he was so blindingly good at all parts of his job. Matthew particularly endeared himself to me because he had a generalist’s brain, not a specialist’s. That is, he was capable of narrow focus when he needed it, but also saw the big picture. And he cared about the big picture, and those who needed to work with the big picture.

Matthew’s greatest skill was that he could begin his explanation of any part of the product from any point. When I asked him a question, he would make a fairly accurate guess about how much I already knew, and start his answer from there. If I told him I was lost, he’d back up a bit. If I let him know by asking an intelligent follow-up question or making an accurate analogy that I knew a tiny bit of the background, Matthew would always notice that he could jump ahead a bit and speed things up for the both of us. Matthew never got impatient or frustrated with technical writers, testers, executives, or anyone else who couldn’t write code. He could adjust the depth of his explanations on the fly. He could recalibrate much faster than any GPS. He kept the destination in mind, but not only the destination. He adjusted based on where the conversation currently was.

That’s really hard to do. Knowledge isn’t enough. It also demands the ability to approximate what others know and don’t know.

Most of us have forgotten when, or how, we learned a lot of what we know. Our knowledge has become part of us. Which leads to some of us assuming that some of the knowledge we have is generally available. And, ahem, such generally-available things need not be explained to anyone.

Steven Pinker wrote a [paywalled] article, “The Source of Bad Writing” for the Wall Street Journal, the subhead of which is “The ‘curse of knowledge’ leads writers to assume their readers know everything they know”. The core concept applies to thinking as well as writing.

When you have forgotten the effort of learning something, you also tend to believe that anyone can learn it instantly. When developers can easily explain something to other developers, they tend to think that their explanation is something that anyone can grasp just as quickly.

These days, developers and technical writers and testers all work much more fragmented days than they did even ten years ago. But developers with whom I have worked tend to have the advantage of more time in flow state; that is, immersed in a feature. Even now, some developers are assigned principal authorship of a single feature at a time.

Whereas I work increasingly fragmented days with lots of context-switching. I have mere minutes to understand the immediate context of what I am being asked to write about, and never hours. The idea of technical writers having time to understand the context outside the immediate has not even been identified as valuable, let alone addressed.

Developers asks technical writers for something they see as quick for them. It might be a change to a single sentence, or the addition of a single paragraph. They see only the writing work. Worse, anything less than a response time that the developers judge to be “reasonable” is seen as being professionally delinquent.

Non-writers often fail to appreciate how much time the technical writer needs to catch up and absorb the weeks or months of work that led up to the “quick” and “simple” request. The developer has had time nearly every day to think about the topic, and has no idea that it takes time to catch up nor, in some cases, that anyone would need to catch up.

Now we come to the topic of reviewing the text proposed for the user interface (UI), also called string review. In an ideal world, the user experience (UX) team would ask the technical writers to review the whole design, including its text, quite early. Shortly after the basic design had been created, the UX team would present the technical writer with a design of all the UI elements. The rough design would allow the technical writer, or anyone else, to understand how the user can complete a task, or the main tasks.

That’s a very different situation than I have experienced at most high-tech firms. Instead:

Shortly before the feature is ready to be made available to the user, someone asks the technical writer to review the text used in the UI. The idea seems to be that the actual design has to be final before there is any point involving the technical writing team. It’s not ideal for a technical writer to be asked to review the same UI multiple times as the design iterates, but even that option beats the heck out of being asked at the last minute to do a quick polish.

Perhaps there is an idea that all the technical writer is going to do is act as a grammar and spelling check. Perhaps there is an idea that the technical writer takes all things on faith, and makes changes without understanding them. But neither idea is correct.

It’s a rare case of developers feeling frustration with technical writers at the same time that technical writers are frustrated with developers. The former cannot believe how slow the latter is (whether literally or intellectually “slow”). The latter cannot believe the unrealistic expectations of the former.

If you have a lot of experience in technical writing, you’ve doubtless already realized that when you write for users, they want to skip over the conceptual parts of the writing and get on to the procedural parts. This is the same problem, only it’s with your co-workers, not your users. Developers don’t want to know about your requirements, but you can decrease their frustration if you explain the context and the concepts.

Concepts aren’t appealing, like snacks, but they’re necessary, like vegetables. Technical writers telling developers that they have to eat their vegetables is never going to work. No one likes being condescended to. Since some developers see technical writers as their inferiors rather than their team members, the “superior” tone of the message “eat your vegetables” is going to increase conflict rather than improve understanding.

The solution is regular and specific communication—from you to the developers, but also from the developers to you. And since you’re not in charge of when or how others communicate with you, you may have to take the lead in reminding developers how helpful they are being when they communicate regularly, communicate early, and communicate clearly and specifically.

Communication about expectations is key. If someone’s expectations remain unexpressed, it’s going to be impossible to explain why they might need to be adjusted. Because the hidden, underlying assumptions are going to stay hidden.

I remember a TV special hosted by Tom Peters in which Mr Peters was asking the head of a company how they could possibly function with a flat rather than a hierarchical company structure. The company head leaned forward to be sure he had the full attention of Mr Peters, and answered “Tom… we talk to each other.”