Structured writing = commodified writing

While researching doc tool and process options, I’ve been interested in developments in DITA, especially a call for simplified DITA. I’m just surprised that it’s taken this long to get started. But I’ve seen at least one DITA expert say that simplified DITA is good for engineers and other transient contributors. Again, people are stuck in the mindset that only professional technical writers can write “correctly,” and we’re doing everyone a favor by allowing them a peak into our walled garden.

But here’s the thing about DITA, and structured writing in general: It commodifies technical writing. And while that might not be a bad thing, we have to acknowledge that if we go to a fully-structured writing world, one of the consequences is that we turn tech writing into a commodified skill, making it easier for everyone to write acceptable documentation.

And that’s not a bad thing

In a comment on one of my “Death of technical writing” posts, Jang Graat argued against wikis, writing:

But the implicit message that gets me worried about all those wikis is one that I have been hearing for a long time from potential customers: “Hey, anyone can write, right?”

He’s got a point: If we open our documentation to collaborators, we do can inadvertently give weight to the opinion that anyone can write, which further devalues the role of Technical Writer.

But a major goal of DITA is to remove individual writing inconsistencies. To create strict templates that minimize any differences in voice and tone to make sure that no reader can tell that the content was created by different writers.

And if the structure is strict enough, then we’ve created a system that allows anyone to use it (assuming they learn the tools and rules). But it’s the rules of the structure and the authoring tools that are a barrier to entry, not writing ability.

Advantages of structure

To be clear, I do understand the very real benefits of structured writing (and, therefore, DITA). My particular interest is in content reuse; I don’t have other writers to worry about, and we’re not doing any translation (yet). Being able to export to multiple output types is also a clear advantage. There aren’t many other tools that offer those features (although we are seeing more options).

And enforcing structure is good if you need to reuse the content in different ways.

Here comes the but…

But that also forces you to write in tiny, atomic chunks. And then spread those chunks across a CMS. And then figure out how to put them all back together into meaningful documentation.

That’s the part that I always get stuck on: Finding all those chunks once they’ve been written and filed away.

I’ve seen this done very, VERY badly. I inherited a manual that had three chapters:

  1. Concept
  2. Procedures
  3. Reference

Every page included a handful of sentences and a LOT of whitespace. Obviously, this was the laziest, most ineffective possible implementation of DITA. Having to rebuild that into a functional manual was a nightmare, hunting scraps of topics across dozens of folders in the CMS.

The other manuals in that doc set weren’t much better. Although this explains some of my reluctance to embrace DITA, I realize that this was an example of implementing DITA without a plan.

I like links

I like links. But DITA doesn’t. And, again, I understand why: They limit reuse. Links in a PDF should look different from links in online help and in printed manuals. And if you don’t include the linked-to information in that particular doc configuration, then you’ve just created an error.

But…well, just read this article by Tom Johnson and this related post by Mark Baker. Online documentation with a spare list of links is less valuable to the reader than online help with rich linking between topics. And rich linking can also help reduce the need to reuse content, which makes for less cluttered, less redundant documentation.

But that manual linking requires a writer who understands their documentation well enough to recognize that a related topic exists. This is less likely to be true with huge help sets written by multiple writers. So an auto-generated list of related topics is often the best we can do.

So while hand-crafted artisanal documentation might be (arguably) more useful to our readers, it’s more difficult to create and maintain.

Although having a system that creates a related topics list on the fly, based on tags or keywords or whatever, would be very handy. Then you could open the Add Link dialog and pick from a list of suggestions. Just throwing that idea out there.

Somewhat related to the issue of links

This is off my main point, but I take offense at this Techwhirl article that says that it takes a “confident” technical writer to let go of links. Maybe “trusting” is a better word than “confident,”* since you’re trusting that your system will create a good list of auto-generated links, and trusting that your reader will get enough guidance from those lists.

And using DITA isn’t, and shouldn’t, be about bravery. It’s about what best serves your company and, most importantly, your customers (internal and external). If you need structured writing/DITA, then by all means use it! But don’t tell me that I’m cowardly because I’m not going down that path.

Ok, thin-skinned rant over.

*Note: I misremembered the term as “brave” rather than “confident.” I’ve fixed that, but now that I’ve seen my mistake, I agree that “confident” is a better word than “brave.”

Back to my point

So with highly structured writing, we eliminate differences in voice, tone, and overall writing style. We force writers to include a very specific, limited set of information in each topic, and do not allow them to vary from this structure. The more structure you build in, the more restrictive the system is.

While simplified DITA might loosen the reins a bit, that structure is still imposing rules on writers. Again: That’s not bad. There are very clear advantages to that, and very good reasons for doing so.

But it also turns technical writing into a commodity. Again: That’s fine! Heck, I’m arguing that we need to make the tools easier to use, which lowers the barrier even further. But that means that fewer and fewer people can rely on Technical Writing as a career.

The Techwhirl site identifies technical writing as one of many responsibilities of technical communications. In my experience, you won’t get too far if you only have one of those skills. At this point, API documentation is the only exception that I know of, but that type of writing requires more than just a bit of writing and organizational ability. An API writer needs to know how to auto-generate documentation from the code, how to organize and present API documentation, and how to prepare code samples for readers. (“Preparing code samples” might mean writing them from scratch, or taking existing code and making it generic.)

Which means…

What this means is that we can’t get rely on finding a career as purely Technical Writers. We really haven’t been able to do this for a while, and I know I’m not saying anything new. We need to broaden our skills, prove our value to our businesses, and generally step away from the “purebred” technical writer role. As Christine Brouillard put it:

@cebrouillard: Seeing more hybridization of jobs in technical communication. Not just tech writers anymore. #stc14

Becoming a hybrid gives us a better ability to adapt to changes, more skills to use, more responsibilities and ownership, and also keeps our day-to-day tasks from becoming monotonous chores. Maybe it’s just me, and I’m easily bored, but curiosity is a key feature in a technical writ…technical communicator, and we’re always looking for a new challenge.


15 thoughts on “Structured writing = commodified writing

  1. A lot of good thoughts here, Neal. Thanks. Let me just respond to a couple of them.

    Let me suggest that structured writing isn’t turning technical writing into a commodity, but the converse. Technical writing has become a commodity, and structured authoring is one way — the most effective way I’ve seen — of dealing with that reality. We have to provide value, in other words, ROI. Structured authoring, much more than artisanal writing, helps us do that.

    Finally, I agree with you that it’s getting harder to find a career as a pure technical writer — and that that’s not a bad thing. Again, it’s about providing value, and we do that by deploying the whole range of our skills rather than a narrowly focused set.

    1. That’s an interesting thought: maybe I’ve identified the wrong end of the dog that’s really doing the wagging. Artisanal writing is a mess in terms of ROI calculations, where metrics are based on guesswork, so that suggestion makes sense. Thanks!

  2. DITA doesn’t change the game as far as I can see. Even without DITA, engineers can create documentation that is ‘acceptable’, but usually that is limited to step-by-step instructions. DITA doesn’t suddenly make technical experts able to write clearly or explain technical concepts in a way that non-expert end users will understand. We have a different skill set to engineers, marketeers etc.

  3. I’m with Larry on this… Tech Writing risks becoming a commodity wholly apart from DITA or any other tool, technology, or writing framework. Commodity is all about value — it’s a commodity if there’s no special capability needed to add a given value. By definition, it’s a specialty if a special capability is necessary.

    Old-school tech writing claimed the specialized domain of publishing, based on the cost and difficulty of printing on and moving around massive quantities of paper. It’s publishing that technology has turned into a commodity. DITA contributes to commodity to the extent that DITA contributes to the publishing work flow.

    Technical writing is all about adding value to areas within the information management spectrum. To keep from falling into the commodity trap, you have to put publishing in a place apart from writing. You have to let go of page count as a definition of productivity. You have to identify the information needs of your project and adapt to them. That kind of adaptation is a specialized skill, and doesn’t risk becoming a commodity any time soon.

    1. Thanks! I’ve fixed that, and also realized that I misremembered the word as “brave” when it’s actually “confident.” Which isn’t as bad.

      1. Neal, I’m the author of that TechWhirl article. I probably should expand that section to explain that I meant that the better you understand your end users and how they will use the product, the more you can write the focused content they need. The more focused the content, the less likely you are to need to provide inline links to other topics.

        Another important factor is your confidence in the search and navigation of the documentation: if you know the user can find slightly related information easily, then you also feel free to drop the this-is-sort-of-associated-but-generally-just-the-same-subject-area links. You’re left with related topic linking that the user knows is always going to be really important.

        I’ve seen so much content that links to another topic in almost every sentence and step, which just serves to annoy or lose the user. Instead, use a topic to tell them what they need to know; don’t make them go somewhere else to find it. There are always exceptions, but that rule helps you write focused, usable content–which is, as a result, free of unnecessary links.

        And yes, related topic links created on the fly is possible, but is going to need DITA’s subject scheme and classification maps. Automation is possible when the infrastructure is there!

      2. Thanks, Jacquie, and I apologize that I clearly misread that part of the article as “good tech writers will do this.” I agree that the topic should answer the user’s question and not lead them to a dozen more places where they can hunt for an answer. Balancing link frequency is a struggle for any writer, whether they’re writing in structured or unstructured formats.

  4. I agree with Neil on the points he argued in his post. I think there are at least two types of DITA skills: consultant DITA skills, and worker-bee DITA skills. If you’re a DITA consultant, you come into a company and set up their XSLT transforms, set up a publishing workflow, and so forth.

    Once it’s all set up, all the worker bees have to do is fill in the blanks with each topic type, adding a short description, putting instructions in steps, adding screenshots in info elements, and so on. Ultimately, once you set up your publishing architecture, the act of writing in the DITA structure doesn’t take a whole lot of skill. DITA makes it so you can standardize, simplify, and mass produce content creation.

    I recently got an inside view of a company that has the whole DITA process defined. The company has all the XSLT transforms defined and styled, the publishing workflow set up, style guides established, processes and flows identified and implemented. All you have to do is put your DITA files in a certain folder and everything else is taken care of.

    Seems to be like you could hire droves of writers, train them on the DITA structure in about a week, and avoid seeking out the expensive, high-powered type of tech writer that would command more than an average worker-bee salary.

    For me, it sounds a bit boring to have a content machine set up like this. But it’s probably very efficient.

    1. Thanks, Tom. That was the scenario that I had in mind (and I’ve seen similar setups).

      There’s a large initial cost (consultants, training), but you gain a lot of long-term efficiency. It’s suited to companies with a standardized, routine process (plan, build, document, release process). You lose the ability to adapt to changes, but you can publish a lot of documentation very quickly.

      1. I’m sorry, but I can’t agree less. I guess I would agree that the writing you’re describing here is trending toward commodity. But I can’t agree that it’s because of the tool or technology. Maybe it’s that the organization wants writing to be a commodity, and they set DITA up as a way to enable that. But tech writing is a commodity because of the content, not because of the tools or technology. In these types of enterprise scenarios, the writing can’t be a commodity if the organization demands more specialized content… by definition.

        Tom says “…all the worker bees have to do is…” and gives a laundry list of content production activities. That describes the physical production of the artifact. But where’s the knowledge and understanding that drives the physical activity? Nobody needs the obvious to be documented. By definition a commodity is obvious.

  5. Late to the discussion here, but I couldn’t agree more with cud. The moment you commoditize documentation is the moment you start down that slippery slope toward not caring about the content that all that fancy presentation and management is designed to manipulate. I work in a large corporate environment where a lot of documentation is published very efficiently. But to what end? We have such content proliferation with all this efficiency that we now have a task force to figure out ways to reduce duplicate/redundant/out of date content. Yes, part of the problem is in the implementation details. But part of it is in the underlying assumption that automated processes of any sort can replace real knowledge and understanding.

    1. Jennifer: it sounds like your company is spending as much time reducing duplication as it is creating the content in the first place. But does this allow you to focus on creating more complex docs (workflows, tutorials), and avoid spending time writing the obvious stuff?

Comments are closed.