Expertise is an asset

Posted on by

Yesterday, I caught an interesting conversation started by Mark Baker‘s tweet reflecting on the uncontroversial understanding that software developers are less productive when subjected to interruptions:

What followed was some skepticism on the part of Rahel Anne Bailie and Kai Weber about attempting to hire writers who are also subject matter experts (SMEs):

I’ve heard this kind of skepticism about SME writers expressed before, almost as if there’s something improper about subject matter expertise. I’ve heard other writers talk about subject matter expertise as though acquiring expertise necessarily diminishes the abilities of a writer to communicate. And it’s an occasional insecurity of mine that being “just” a writer is inadequate. So I understand that asking for subject matter expertise from writers is a bit fraught.

In agreement with Bailie, there’s a tendency toward over-specification in hiring searches. Organizations often seek to hire a wish list, but wish lists rarely apply for open positions. For most organizations, a more realistic expectation is to hire a person who has a few characteristics of the wish list, combined with the enthusiasm and ability to learn the rest. But if an organization can get a writer SME, then they should, as it is a powerul pairing, at least in the software business.

Asking a writer to go through specifications or other documentation, or through SMEs themselves, to understand software is a bit like playing a game of telephone. Yes, the message will get through eventually, but errors routinely creep in. Specifications reflect aspirations and goals, not working software. In contrast, code doesn’t lie. Code provides a kind of clarity about software that is beyond the reach of the most thorough SME interview. A writer-programmer doesn’t have to play telephone.

At one point in the conversation, Baker asked, “which metric do [companies] care about most, developer productivity or content quality?” as if the two were necessarily in opposition. But expertise in one area doesn’t have to come at the expense of another. Companies that have SME writers don’t have to choose between developer productivity and content quality, because paired expertise is often complementary.

Consider a simple case, one I’ve faced dozens of times, in which I’ve needed to document the acceptable values for a form field. One way to deal with this is to turn to the developers and ask, “what are the accepted values in this form field?” This approach necessitates an interruption, but doesn’t require any expertise in the software’s implementation. Another approach, and frankly, a better approach, is to take a peek at the form field’s implementation, to see that the field validates on a regular expression that unambiguously describes the accepted values. The documentation can more closely adhere to the reality of the software, and less developer time is spent recapitulating the source code.

So, just as Baker pointed out, a writer SME can consume less of a developer’s time trying to understand software. That’s not to say code is the whole of understanding software. SMEs must be called upon to share intentions and expectations that code doesn’t or can’t capture (in the example case, the implementation may not have been the intended one), but the importance of code is hard to overstate. A writer with subject matter expertise can work without relying solely upon the intercession of other SMEs. A writer-programmer can go directly to the source of truth about the system.