Responding to Craft vs. Commodity

Connie Giordano has an interesting take (and a reader poll) on technical writing as a craft vs. a commodity. She’s writing something of a rebuttal to my post about the same topic. When I checked before posting this, the results were tilting towards “Tech writing is a hybrid profession,” slightly ahead of “Heck yes we’re craftspeople!” I voted for “hybrid” even though I’m not entirely sure what that means. But I think it’s closer to my argument.

And the answer is…

This result surprises me: I assumed that with the readership of Techwhirl would lean heavily towards the statement “Tech comm is a craft that requires skill, acumen, and ingenuity.” I mean, that’s seems like the most tempting answer for techcomm people (myself included). If only she’d written “requires skill, acumen, ingenuity, and breathtaking levels of sexiness,” then I bet the results would be leaning the other way.

Ok, I’m poking fun, and that’s not fair. Because her post is very fair, and she’s written a good analysis of the issue. This statement in particular got me thinking:

But the act of creating content is a far different thing than the act of delivering it to the targeted audience. Well-implemented standards to help structure and simplify content may drive efficiencies and improve the bottom line, but will that resulting content resonate with a user and make their lives easier or more enjoyable?

There’s a lot of stuff packed into those two sentences. It’s true that creating content (written, visual, video) is not the same as presenting that content to the customer who is turning to the help (knowledge center topics, videos, PDF manual, whatever). I think we’ve reached a consensus that content creation and content publishing should be separated, and the person doing one shouldn’t worry about the other (at least not while they’re engaged in either end of the process).

Creating vs. publishing

That’s a convoluted way of saying: when you’re writing the docs, you shouldn’t think about the formatting stuff. And when it’s time to publish that content, the person doing the publishing shouldn’t have to understand how the content was created.

But…we do, don’t we? We might not worry about the specific font that’s going to be used (but good luck finding a tech communicator who isn’t passionate about fonts), but we do need to indicate when something will be displayed in a different way. Whether you’re just applying bold to a word, or tagging it as a UI control, or building a video as part of a channel, or sequence of videos, you are determining how that content appears to the user. The details are defined separately, but we still need to make that determination during the creation process.


And then there’s this sentence:

Well-implemented standards to help structure and simplify content may drive efficiencies and improve the bottom line, but will that resulting content resonate with a user and make their lives easier or more enjoyable?

And I honestly don’t have a good answer. My immediate response is: No! Any content built from tiny blocks of carefully neutral (and neutered) language, stripped to the barest essentials to allow for maximum reuse and ease of translation, will not be engaging. It’s the techcomm equivalent of boiled vegetables: bland and mushy. All of the character and tone has been leeched out of it so the content can be slotted into any context without looking awkward. Or interesting. It’s just one of many bland, monotone building blocks used to construct the product documentation.

Except…Lego pieces are also bland and monotone (ok, not all, but work with me). And damned if you can’t build some amazing things with pieces that are pretty boring on an individual level.

Art vs. commerce

But I don’t think that many of us consider ourselves artists. Structured writing reduces any artistic idiosyncracies that can make each piece of content a little too lopsided to interlock properly with the other blocks. We’re doing a job, and we’re looking to maximize the quality of what we produce, and very often the quantity, too. While reducing overall costs.
But: “will that resulting content resonate with a user and make their lives easier or more enjoyable?”

I wish that “Yes!” was the obvious answer. But if you write a piece of content as a whole (a single workflow topic, or an overview and then a procedure), you build in a sense of flow. Assembling a document from sub-pieces doesn’t allow for that flow.

Every chunk of content is a commodity, to be tagged, cataloged, and used wherever and whenever possible. Will this resonate with the user?

Should it? We want to answer a question as quickly as possible. Our job is to help the user get back to work and produce value for their company (and thereby justify the value of our product, increase sales, and so on). The content needs to “resonate” with that user to avoid or calm the user’s frustration.

Maybe a sense of flow isn’t required. Maybe the readers don’t notice, or can accept a slightly disjointed topic in exchange for focused, streamlined information. And what would “flow” look like for an API reference, anyway?

Back to the death of technical writing

One last observation. Connie Giordano’s bio includes a skill summary that should be familiar to many of us:

She can change hats faster than a NASCAR driver at a press conference, switching between technical writer, knowledge manager, information designer, product manager, pubs manager, project communications lead, UI designer, communications consultant, and change management specialist, among others.

This is the point I’ve been trying to make: Even though she “serves at the Editor for TechWhirl’s Tech Writer Today online magazine, as well as a frequent contributor,” she’s clearly not “just” a technical writer. Connie lists an impressive array of skills, many of which fall under the “technical communicator” umbrella. But product manager and change management specialist are entirely different fields, and extend far beyond what the traditional Technical Writer role includes.

You don’t need to build a site like TechWhirl to stay relevant, but relying on writing and editing skills alone just won’t work anymore.


5 thoughts on “Responding to Craft vs. Commodity

  1. Hi Neal,

    In my world, “breathtaking levels of sexiness” are a given 🙂 Seriously, thanks adding more interesting nuance to the discussion.

    I think where a lot of the debate turns is on that separation between creating content (in whatever format) as a technical writer, content developer, or whatever is the hot new job title this week, and delivering that content as a content engineer, or technologist. They are quite different ends of the spectrum as you say, but we need awareness of the other end while we working in the one. I think it’s nearly impossible to write topic-based content without an awareness of how that content could be combined with other content, or whether it will stand alone. It reminds of the debate on the TechWhirl discussion list from years ago, where some folks (content engineers) were adamantly on the side of structure first, and others (me included, back then I was different) were adamantly content first. At the end of the day, we were both right and both wrong concurrently.

    Perhaps it’s time to consider which lens we use during each part of the cycle. When planning technical content, you need to have that strategic, or wholistic lens, including knowing the organizational objectives and understanding all of the contexts in which users want or need to access the content. That’s a different perspective than being the content developer (er… technical writer) who needs to efficiently communicate a single procedure or concept… Or the content engineer’s perspective of producing a single procedure or an entire book in the right form for consumption. There’s no one right perspective, only the best perspective for the task at hand.

    All of this does present even more interesting challenges, and potential career paths, than the simple “Technical Writer” title implies. That’s where the fun comes in, and over on TechWhirl, we’ve got a whole set of hats ready to switch out at a moment’s notice 🙂


    1. The lens idea is a great one: There’s the question of how much the creator needs to know about how their content will be used, and how much they should be expected to know. (Or: What’s the cognitive load involved in creating content?)

      Creating very streamlined, minimalist content (which also means very few links to other topics) reduces the cognitive load, so the creator doesn’t have to worry about the potential uses (more complexity = more things that can go wrong).

  2. It seems to me that you are forgetting the most important skill that (good) technical writers possess – the ability to explain. That is our art. It is not just about writing in plain English and thinking about re-use and the target audience; it is about explaining things in a way that readers, often of different technical levels, understand and relate to.

    As a contractor, I often have to work with content that has been created by other technical authors who have since moved on (left the company, not died!). Sometimes they were trained in our discipline, other times they were ex-technies-turned-writers. And the difference in quality is often quite apparent…usually because they have committed one or more of my pet hates – described the product rather than explained how to use it; explained it in technical terms that only make sense if you understand the terms/concepts in the first place; only explained what to do when the product works as expected.

    Lee Lefever’s book, The Art of Explanation, covers a lot of interesting stuff, even though he is a video content guru.

    1. That’s true, and there’s also the knowledge of what to write and what can be left unwritten. That’s particularly important in the modern agile environment, where the writer barely has time to focus on a few important whats and whys to document.

      My bias is that I’m looking at technical communications as a full-time career. I’ve seen a lot of companies treat the documentation as an afterthought, and they’ll parachute in a contractor near the end of a project, have them churn out some docs, and then let them go. A contractor writer rarely has any influence on the product, and is probably stuck using whatever doc tools and processes that former writer left behind.

      Instead, I want to be involved in the product from the beginning (or close), so that I can really understand what needs to be documented and how it needs to be presented. I want to build the doc tools and processes (which, to be honest, is another possible role for a contractor). And I want to build the long-term product knowledge that allows me and my team to create quality content. So I’m trying to figure out how to build a career like that in the current business environment where speed is the most important thing, and everyone is expected to wear multiple hats. It’s possible that I’m fighting the tide, and contracting is the future for technical writers.

      1. I worked as an employed technical writer for 17 years, so can understand where you are coming from. What you are looking for is a company that knows it needs documentation but hasn’t the expertise to put it into place. The problem is (in the UK, anyway), that companies like that tend to develop and sell their product first, then panic about documentation as the delivery date looms. So you are always playing catch-up and making compromises. The management level roles you describe tend to involve inheriting a documentation legacy that can be difficult to change.

        For me, contracting was the future because of the variety of work it can offer. It drove me nuts writing about the same type of product for so many years. But back then I didn’t have the finances to take a chance and go freelance. Oh, and for what it’s worth, as a contractor, I’ve had just the same sort of influence as I had as an employee – I’ve made design suggestions, created documentation processes, documented other processes etc. I just see that as an extra part of the job. Of course they don’t always listen, but was the case as an employee too.

Comments are closed.