Adding Value as a Technical Writer

Tom Johnson recently reflected on the tension between increasing technical expertise and focusing on other aspects of technical communications, such as the tools and processes around writing and publishing.

Another Frame: Adding Value

In part I found his post intriguing because it has to do with constraints. There’s never enough time for everything. We have to choose. But then something gets neglected. Or at least that’s the way I usually feel. However, a more productive way to frame this problem is to consider how to maximize value added. When framed this way, choices aren’t negative, they’re about selecting the most beneficial path. So the question is: What adds the most value?

An important caveat here is not to over-analyze what constitutes the most beneficial path. I’ve found myself stuck in a loop when I ask, “This is good, but is there something better I could be doing? What is the best option?” At some point, motion is better than analysis, and continuing the analysis is worse than simply selecting a good option. (See also: “The perfect is an enemy of the good.”)

In many cases the value added via one path is sufficiently greater than the value added via another path that the choice is easy. That doesn’t mean path A is bad. It just means path B is superior.

Determining Value Added

If the better path is the one with more value added, how do we determine whether more value is added by increasing technical expertise or by focusing on other aspects of technical communications? I think much depends on the circumstances. Consider the following cases.

When a lone writer authors all the documentation at a small company, it’s probable that deep technical knowledge could only be obtained by diminishing the quantity of docs written. Since there’s a single writer, the effect of fewer docs could be far greater than if that writer were on a team of 20 writers.

Given a team of 20 writers, the quantity of docs written is likely quite large, so someone on that team had better have serious knowledge of authoring/publishing workflows, information architecture, user feedback analysis, search optimization, and the other tools-based or process-oriented emphases Tom mentions in his post.

But is deep technical knowledge really what a writer ought to aim for? I disagree with this claim Tom makes: “without deep technical knowledge, it’s almost impossible to write coherently and intelligently about the product.” Tom’s questions are about emphasis. I think it’s fitting to think about this problem as one of degrees. Writers don’t have to be able to single-handedly produce the technical product in order to explain it.

I wouldn’t aim for deep technical knowledge. I would aim for adequate technical knowledge, recognizing that what constitutes adequacy may vary by project, and that technical knowledge ought to grow over time due to immersion in the documentation and exposure to the technology and the industry.

I speculate that the need for writers to have deep technical knowledge diminishes as Tech Comm teams grow in size and as other skills become more important than they are for smaller Tech Comm teams. I’m not claiming that deep technical knowledge is useless. I’m suggesting that (to frame it negatively) neglecting deep technical knowledge has less severe consequences than neglecting content curation, doc tool set, or workflow considerations.

Example of Adding Value

I’ve been working recently on creating a little tool that, for a given doc article, displays a list of “pages that link to this page”. It is intended to aid writers as we analyze where to make doc updates/additions when a new software feature is introduced. We have quite a few writers in our company, so this tool will be used by several folks.

In addition, its technical availability doesn’t require anyone to build additional functionality into our publishing platform or add new metadata. This information is already available in the publishing platform’s API. I’m just exposing that content to the technical communications team members in a way that is easy to view.

My hope is that this small addition to our doc tool belt will make it easier to understand how the docs fit together. In other words, I’m hoping for a good return on my time investment.

Conclusion

Another consideration is whether the knowledge or skills any given writer possesses are such that others in the company could pick up slack if that particular writer fell ill or was away for an extended time. Our team has a schedule that shows who’s available to help with particular Tech Comm skills during the holidays, including creating new accounts for access to our docs, escalating or resolving bugs/issues with our publishing platform, and responding to doc inquiries. If a task was not accomplishable due to the absence of a single team member, that would be a problem. Can the same be said for a writer’s lack of deep technical knowledge?

It may sound like I’m presuming the answer is “No” but it’s an open question. Perhaps a lack of deep technical knowledge leads to flawed, misleading documentation. That would be a problem. If you work in an industry that requires deep technical knowledge to contribute to the doc set, you should have deep technical knowledge.

My overall point is that there are sometimes diminishing returns on investing time in an area. And we’re always choosing one path over others. The questions are: when or where does that diminishing occur, and what available options maximize the value you can create from where you stand?

Advertisements

Ordered Lists and Data Integrity

WYSIWYG editors usually allow you to create ordered lists. In HTML, ordered lists look like this:

<ol>
	<li>Buy ice cream</li>
	<li>Open ice cream</li>
	<li>Eat ice cream</li>
</ol>

But imagine you want to add a tip after the “buy” step. In your editor, you might add a line after the first list item, add your tip, and then start the list number where you left off. Here’s one way the HTML might look after doing that:

<ol>
	<li>Buy ice cream</li>
</ol>
<div class="tip">Bring a cooler!</div>
<ol start="2">
	<li>Open ice cream</li>
	<li>Eat ice cream</li>
</ol>

Here’s what that looks like:

  1. Buy ice cream
Bring a cooler!

  1. Open ice cream
  2. Eat ice cream

Perfect, right? Unfortunately, although this might look okay in an editor or even in the resulting web output, the data integrity of the list is broken. When you look at the content in a WYSIWYG editor, what you appear to have is a single list with a tip connected to the first list item. But what you actually have is two unrelated lists with an unrelated tip between them. Why is this a problem?

Consider what happens if you decide you forgot a step. You add one:

<ol>
	<li>Find ice cream</li>
	<li>Buy ice cream</li>
</ol>
<div class="tip">Bring a cooler!</div>
<ol start="2">
	<li>Open ice cream</li>
	<li>Eat ice cream</li>
</ol>

Output:

  1. Find ice cream
  2. Buy ice cream
Bring a cooler!

  1. Open ice cream
  2. Eat ice cream

Now there are two number twos and no number four. Instead a better approach is to integrate the tip into the list item it’s associated with. Then let the ordered list auto-number all the way through:

<ol>
	<li>Find ice cream</li>
	<li>Buy ice cream
		<div class="tip">Bring a cooler!</div>
	</li>
	<li>Open ice cream</li>
	<li>Eat ice cream</li>
</ol>

Output:

  1. Find ice cream
  2. Buy ice cream
    Bring a cooler!
  3. Open ice cream
  4. Eat ice cream

This approach prevents accidental misnumbering. It also makes it possible to do potentially useful things, such as query your content set to find out the average number of steps in your procedures.

Structured Writing

By day, I’m a technical writer at a software company. Our main publication platform is a cloud-hosted web-based content management wiki system developed as a self-service customer help portal.

We use templates that guide our document creation. The templates serve as starting points with suggested headings and example structures. But the writers can ignore the templates or wildly alter them, which is why we also have a structural review process.

We have a style guide that dictates processes and standards common across our document set. But a style guide can’t cover every scenario; it’s bound to have gaps and leave many questions unaddressed. Neither can it enforce its own standards, which is why we have a peer review process.

Since this is only my second year on the job, I’m keen to learn the strengths and weaknesses of the approaches and tools we use, as well as alternatives. One such alternative is structured writing, which aims (among other things) to avoid the weaknesses I noted above inherent to using templates, style guides, and reviews to maintain structural and stylistic consistency.

In structured writing, architectural decisions are separated out from the authoring process. In other words, writers work within structures rather than creating structures as they go.

To some extent this describes my current job processes. Each article exists within a preexisting (or at least predefined) hierarchy. For example, a guide consists of topics, which in turn are populated with a set of articles. Thus, some degree of architectural decisions are already a given rather than resting on the shoulders of the writer.

However, structured writing, if I understand it correctly, does more than enable you to specify how page-level content ought to be nested or ordered with respect to other page-level content. Rather, you are able to construct and then work within a hierarchy that is both broader and more granular. An example of the hierarchy being broader is specifying the allowed set of page-level content types, such as recipe, procedure, and concept. An example of the hierarchy being more granular is specifying rules, such as “icons can only appear in paragraphs, not in headings or page titles.”

Shifting architectural decisions out of the authoring process has a number of benefits.

  • First, it means these decisions don’t have to be constantly re-hashed. Once the hierarchy is set, that doesn’t mean it cannot be altered, but it does mean the hierarchy is not re-open to discussion every time a new piece of content is authored.
  • Second, it reduces style guide bloat. For example, you can remove style guide instructions that require every diagram to have a title if the `diagram` objects always, by definition, consists of a title and a reference to the diagram image file.
  • Third, it reduces the burden on writers to keep current with managerial and architectural preferences. These considerations are not inherent to the subject matter content being authored. Instead, they are overhead costs that, at least in theory, can be reduced by embracing structured writing.

Right now I’m still exploring the various process and tools available for structured writing. But you can expect more on this subject in the future.

Quote

Expertise and discovery

…writing anything as an expert is really poisonous to the writing process, because you lose the quality of discovery. So every time I felt I knew something particularly well I tried to unlearn it, and learn new things.

  • Siddhartha Mukherjee, author of The Emperor of All Maladies: A Biography of Cancer

(Quotation source: The Guardian: Siddhartha Mukherjee: ‘A positive attitude does not cure cancer, any more than a negative one causes it’)

What does it mean to write as an expert? What does it look like to retain the quality of discovery in our writing? Can what has been learned be unlearned? Or, if not, how does a writer experience discovery anew and convey that experience to the reader? Is this “unlearning” a rhetorical technique that helps the writer get inside the mind of the person who has not yet learned that subject or area the writer is an expert in, or does it get at something more than a maneuver in the mind of the writer? If the latter, what does it get at? A fresh approach to a familiar subject? Asking new questions? Re-framing? If more, what more?