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:
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.)
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.