The death of technical writing, part 1

For a few years now, I’ve been worrying about the future of technical communication as a career. Not that user docs will disappear (as much as most people might want that), but techcomm as a unique job title, as opposed to one of many tasks that someone might have. I remember hearing Noz Urbina telling us that we were doomed, back at Lavacon 2012. And I attended a few webinars at that time that were also very negative about future prospects.

They’re right: We’re doomed. Pack up your pens and find another use for that English degree.

I’m exaggerating. Right?

Technical writing/tech communication is going to be around for a while. But I think it’s going to be more common to see that job title in legacy industries. You know, those places where writers still write *manuals*.

So industries where there’s lots of rules and regulations and everything must be thoroughly documented. Those rules change slowly, after all. And larger software companies that have huge, complex products (databases, for example), which are going to stick around for a few more years, at least.

At least in some form, and for an increasingly limited number of pure technical writers. To be honest, I’m seeing more job postings than now, mainly for senior technical writers. So there’s still jobs to be had.

But apps really scared us, right?

Apps are the worst, right?

Apps are utterly horrible things that don’t require documentation. Or at least not nearly enough documentation to justify a full-time writer. Apps provide a simple, targeted workflow (ideally), with streamlined UI that doesn’t need a lot of explanation.

Which also means that you’re not going to do full database administration or build a billing system on your phone, but more people using apps instead of desktop software means fewer people reading manuals.

And I think we’re the only ones who worry about that. Unless we’re the ones using the apps, and then we admit to a small amount of pleasure that we won’t have to read yet another poorly-constructed manual.

But apps aren’t replacing enterprise software. At least not entirely. Not yet.

But I still think we need to adapt to a changing world.

What have we done to deserve this?

We’ve walled ourselves off, building a fortress of complex tools that no other teams can penetrate. At the same time, we’ve seen successive waves of programming languages, each one easier to use than the last. What are we seeing? Simplification. Ease of use. A learning curve that gets less steep every time. Languages that drop features that aren’t used, or aren’t used often.

And what has techcomm poured resources into? DITA. An arcane, overly complex language with a massive learning curve that requires specialized tools.

Why are we doing this? Because we’ve been trying to cram every possible feature into it that will allow tech writers to rewrite those massive manuals that we’ve been writing for years.

We’re retaining complexity when we need to reduce it. We’re holding on to features that don’t make sense in a modern, mobile world.

What are our coworkers going with? Wikis. WordPress. WYSIWYG editors and tablet apps.

Throw it away

When I switched from Structured Framemaker to a wiki, I was shocked by how much I couldn’t do. I lost an enormous amount of control over the structure of my documentation, from the overall layout to smaller things, like picture captions (I tried; they never worked well).

And then I learned what I could do, encapsulated starting with a single reference topic. The basic syntax was…well, basic.

But it worked. And here’s the thing: My audience didn’t complain. Our customers (yes: customers) aren’t looking for the perfectly-styled documentation that follows strict rules that make sense to us and no one else.

Where’s our drag-and-drop documentation?

I need content reuse; I don’t need to write a manual. My customers don’t want manuals, they just want to know how to use the features in the product that they purchased (or that their bosses purchased and they have to learn to use).

Basically: What does this thing do? Ok, then how do I make it do that? And what else can it do that I haven’t even thought of?

I know DITA makes sense for many, many writers. You want to be able to reuse each and every piece, and enforce a very strict style? Yeah, DITA’s where it’s at. I just think it’s packed full of too many things.

I want drag-and-drop documentation. I don’t want arcane tags and references and IDs. Yes, I know how powerful those are; but so are pointers in C++, and those are a notorious source of frustration.

I want a clean, straightforward, easy to use documentation tool that, most importantly, won’t get in the way of the writing that I have to do. I don’t want think about every tag for every sentence. I just want to research, write, and publish as quickly as possible.

The treadmill is speeding up

Unlike the old days of writing manuals where projects were measured in months, even years, today my projects are measured in hours.

In the last week, I:

  • Launched a massively updated knowledge center, with the help of contractors who designed and coded the CSS. It’s a really nice site, and I’m sorry it’s behind a login.
  • As part of that, I needed to copy a lot of content, reorganize content, and fix every link in the docs.
  • I needed to copy content to support a second product, and rewrite many topics to change the product name and small differences in functionality.
  • I needed to write new documentation for that product (although that was just two new articles).
  • I had to build a structure for project documentation on our internal site.
  • And I had to answer support tickets.

“Become a DITA expert” does not fit into that schedule.

But it’s bigger than DITA

Yes, I’m ranting about how DITA isn’t absolutely perfect. Again. DITA won’t save technical writing, but it also isn’t killing it.

“Unnecessary complexity” is only one thing that’s hurting our profession. The real problem is this: What does a technical writer do for the business? What business problems do they solve?

We’ve been told, and have unfortunately accepted, that user documentation is a “necessary evil” that businesses must deal with. But that’s a stupid, self-defeating reason, and the obvious next question is: Fine, but what else do you bring to the company?

Being able to write good product documentation isn’t enough. Being a DITA expert isn’t enough (or not enough for more than a handful of people).

In the next post, I’ll tell you about what I see as some solutions to this problem.

Advertisements

65 thoughts on “The death of technical writing, part 1

  1. Neal, thank you, for the inspiring article. You are spot on with your questions: “The real problem is this: What does a technical writer do for the business? What business problems do they solve?”
    A fellow technical writer once asked these questions to me: “Which master do you serve? Is it the customer? Is it the developer or tester? Or, is the person who signs the paycheck for you?” My answer to his questions was both intuitive and effective. I replied that I served the supreme master: The Need. Even though I feel that we are making our world complex, I see that a lot of us like to spend the most part of our day in simplifying things/tasks around us. We are there to server to the need–of simplification. Of course, the approach changes with person and preferences, but the central idea is still the same.
    And, as far as your point about the death of technical writing is concerned, well, I think as long as we continue to serve to this supreme master (of need) our profession will keep itself from its death.

  2. Neal’s post is fantastic.

    Regarding the profession, if not dying, it is at least under siege. We need to be cognizant of that and not pretend that some tool or platform is going to rescue us. Whatever we call ourselves, at the end of the day we need to be able to add value to a given offering from the guys who sign our paychecks. And who will decide that value? Readers. Readers. Readers. Platforms do not satisfy readers. Only our value-add does. The clear trend for hiring in the software world is toward content producers who can write in highly technical terms or who have excellent skills producing multi-media content. I have a very hard time hiring a generalist any more. Software users are more sophisticated than ever, and software companies are trying to simplify interfaces and provide services. Read “Consumption Economics” for the pressures driving this.

    On DITA v. wiki: ultimately (and sooner than we realize) the semantic web (and related innovations) will make DITA irrelevant. An open-source AI engine will patch together content in a few seconds. And a wiki is more than a collaboration tool: it is an extensible engine for delivering query-ready, hierarchical collections of online pages that can be presented in read-only fashion. You can make of it what you will.

    1. Thanks for the kind words. And thanks for reminding me about the semantic web idea. I hadn’t had that in mind when I wrote this, but I agree that it’s something we need to consider.

  3. While I appreciate the effort all of you make in your comments, I think collectively you guys are missing the point.

    You are correct in your fears about the technical writer of yesterday being doomed–but you miss why. The fact is, nothing could be further from the truth when you state that “Apps” and programming languages are becoming so simple that documentation is not needed. The fact is the various languages, platforms, frameworks have created a huge need for developer-centric documentation–and the need is being met by crowd sourcing the documentation.

    Crowd sourcing as the primary means of authoring is why the tech writer of yesteryear is dead. Another point absent from the discussion is what is meant by “documention”–given Web2, documentation can be far more than Wikis or manuals–it can be Q&A sites (think StackOverflow–which is one of the most telling trends in how languages, frameworks, APIs are being documented via crowd sourcing), YouTube videos, regular web sites, portals, in-code documentation, blogs, doc metaphors on social platforms like GitHub.

    It is not an exaggeration to say a revolution in documentation is happening, and has been happening for the last 7 years. Worrying about Dita, wikis, structured approaches, etc is just missing the point. And if you miss the point, you can’t know how you need to evolve to remain relevant.

    My belief is that indeed, the tech writer is dead–replaced by crowd sourcing. That said, crowd sourcing is not without problems–one can argue there is a need for (if not possibility of) a new role emerging that tech writers can evolve into–e.g, a role that brings added value to crowd-sourced authoring–that value could be as gate-keeper to better edit, structure, and standardize submissions, coordinate/implement various crowd sourcing platforms/tools/strategies, working with key “crowd” members to teach them how to writer in a meaningful way–etc. Opportunities are many–the question is how to translate them into an actual job. The landscape is fundamentally changing.

    Focus on the need for developer-centric subject matter about how to implement platforms, APIs languages, etc. Focus on crowd sourcing and social networks as the paradigm for development of just about anything in business these days… and the implications thereof…forget about user guides, dita, and wikis, or you will indeed be rendered irrelevant in short order

    1. Derwood,

      Earlier this week I gave a presentation at the Spectrum Conference called “A Voice in the Choir: Technical Communication and the Colloquium of the Web” in which I made a very similar case — that the professional tech writer is no longer singing solo, but is now a voice in a choir of community written content.

      But I believe this actually opens opportunities for tech writers to add value to companies. The existence of an active user community is more important than ever for companies, and the existence of such a community is often a vital part of the buying decision for a technology. Tech writers can contribute to the growth and flourishing of such communities.

      Because the choir exists, users tend to Google for the information they need, and companies lose the ability to grab that traffic is they don’t have high quality web-ready technical content available. Great content on the Web can enhance the company’s reputation for expertise in the field, which in turn draws more customers to the company.

      And today, the majority of the decision-making process for a product purchase takes place before the prospective customer ever contacts the vendor. Thus tech docs can be the entry point of the customer into the company’s content and can have a direct impact of lead generation.

      Building communities and generating leads are not the traditional role of the tech writer, but they are hugely important to a modern enterprise and could provide a more high-status career for the tech writers who learn to work this way.

      1. I agree–regarding the opportunities that exist–I would add what I touched on in my first post: tech writers looking for growth/opportunity may find what they are looking for if they focus on developer-centric content–the technological changes of the last 5 years have created enormous opportunity in this area–to capitalize one needs true developer skills–like fluency in several languages, platforms, frameworks, but one can get educated if one is so inclined.

        Second, I think there is lots of potential opportunity for tech writers to morph into a “new role”–like Ialso touched on–like a gate keeper, or content platform integrator/specialist–but these roles are really “new”–they don’t exist yet, at least not in a industry sense. Enterprising tech writers are only now beginning to see the opportunity, and try to get organizations to also see the same need/opportunity. So capitalizing on these opportunities is a huge challenge.

        A central strategy for such a tech writer is to become very educated on crowd sourcing–there’s is plenty of research about crowd sourced documentation in software–and then assess where the shortfalls exist–they do exist–and that is where the value can be added.

        One last thought: I would ditch the term “technical writer”–there is a lot of legacy negative bias about what a tech writer does–and given that these new roles may be rooted in fundamental tech writing skill sets,, they are much different roles, and thus a different title makes sense–especially to convey the value/expertise inherent in the role.

      2. In the same theme with crowdsourcing, I’m looking for a platform that allows me to store content in Markdown and provides the ability to add comments in the margins similar to Google Docs. I’m currently using Beegit but want to see what other possibilities are out there. Do you know of any?

        BTW, I completely agree with derwood’s comments here. This is one reason why I’ve focused more on developer doc even though the theme of many conferences lately has been “the customer experience” (which usually involves integrating with Marketing). Developer and managing content from multiple contributors is the future of tech comm.

      3. regarding: “I’m currently using Beegit but want to see what other possibilities are out there. Do you know of any?”

        I have of late been required to produce documentation using GitHub’s documentation support features–GitHub is more than just code management, it is a platform to support workflows for development teams. In terms of documentation, documents are treated just like source code–they are authored in markup (I am no fan of markup), and stored and managed in a repository–either with code or in repos just for the docs. Updates/additions are done via branching, just like code. Anyway, to answer your question, there is a workflow called fork/pull request–content submitters (be they developers, writers, or other “members of the crowd”) fork a document repository–meaning a contributor has a complete copy of the repo’s content that can be updated in any way the contributor likes.

        When the contributor wants the updates reviewed–a “pull request” is submitted. a pull request alerts the people named on the request that updates are available for review on GitHub. When one reviews updates to such a request, GitHub has a feature that allows one to make comments directly in the document–the feature has a diff capability, so you can see what the update was compared to original, so a comment can be placed right where the update was—or anywhere else in the doc. Others, including the author can comment on the comments, so it becomes like a conversation over changes. (You can see how this tool facilitates crowd sourced authoring)

        The end result of this process, is that, once approved by content owner, the update is finally merged into the project repository and becomes part of the “official documentation base”.

        Check out GitHub and see if it works for you

      4. Derwood: Check out Tom’s series of posts about his exploration into the world of Git and Jekyll (http://idratherbewriting.com/).

        I’ve been hesitant to jump back into this. I agree that crowdsourced docs are worth pursuing (I’ve done a bit of that in the past and I really enjoy working that way), but I keep running into companies that insist on creating proprietary information, locked behind login screens because they’re terrified that their competitors will mine the content.

        And as Tom says, there’s a growing market for people who can create developer documentation. Although I’ve also seen some of that turning towards a mix of autogenerated docs and content created through a Q&A/customer support process. Which is reactive, but it’s also less expensive and often seen as a good enough solution for small companies.

        I just started a new job as a training manager. Instead of creating online help, I’m responsible for developing content for in-person and web-based training, as well as supplemental content (basically, a knowledge base that customers can reference after training). Oh, and I also need to manage the trainers and generate a profit.

        Why the hell would I do this? Because someone asked nicely, and because I think the time of technical writers as a cost center is fading quickly.

      5. I will check out the post on Git/Jekyll–I have been looking at implementing Jekyll at the same job I now have.

        Regarding your hesitation to jump back in the crowd-sourced/git world (if I am understanding you correctly)–I work for a major financial/media company–there is an enterprise version of GitHub called (fittingly) GitHub Enterprise–this software is identical to GitHub, except it is licensed for private hosting–for exactly the reason you state–so the company can have total control/privacy over the code/content.

        The reason this company is using the product is because they want to attract top developers (they employ thousands of developers)–and the fact is, open/crowd sourced development is the reality today–so, they reason (and I think rightly) that in order to attract top talent, they need to use tool sets that the top talent of today uses–hence GitHub and the workflows it supports. I suspect this trend is evident in many corporations, although I don’t know the facts about this.

        Anyway, in my case, the thousands of developers are being encouraged (if not required) to be responsible for using the documentation tools in GitHub to create documentation–exactly as is happening in the open source community.

        So if you are hesitating due to a fear that the open source/crowd source way of doing things will have only limited adoption, that may not be the case. In my opinion, it is not the case. These methods are impacting nearly every profession and workflow in businesses due to the never ending drive to cut costs and increase profit.

        One opportunity that exists for all the are interested is to contribute to open source projects–there’s literally hundreds of major brand open source projects to choose from, and given how much most dislike documenting, the need is always there–working on such a project is a great way to get street cred in terms of transitioning to developer-centric documentation–and of course to experience first hand the ins/outs of git and crowdsourcing

      6. Sorry! I meant that I’m hesitant to jump back into this discussion at all, since it’s been almost a year since I stirred up this big fuss.

        But I appreciate your comments, and I agree that “open/crowd sourced development is the reality today.” Developers are expected to have Git portfolios, and it won’t be long before that’s standard for people in technical communications, too (much like Tom is doing).

        I’ve been pushing wikis for a while, although I acknowledge that there are serious problems with those systems (it takes a lot of get people to use them, and when they do there’s a high curation requirement). But now that Git/GitHub has taken off, there’s a new crowdsource paradigm that techcomm needs to become familiar with. I’ve only dabbled in it, but it’s something that our field can’t ignore.

        That said, I slightly disagree with Tom: I think there is a reason to ally with other departments, including marketing. It’s a matter of finding where you can add value to the business, and limiting our vulnerability (a tech writer assigned to an engineering department is always the last person to be hired and the first to be laid off). There’s a huge opportunity to improve what we deliver and how we deliver it by focusing on customer needs, and we do that by getting into customer-facing organizations. Maybe this is just a short term solution, but I think it’s another valid path for technical communicators (path 1: focus on developer docs; path 2: focus on customer research and enabling customer success through multi-channel delivery).

  4. Whether we call it the ‘need of the hour is crowd sourcing’ or ‘technical writers need to get involved at a much early stage of product life cycle’, this is the right time to get the three disciplines – technical writers, content strategists, and content marketers closer than ever before, and we all work together in an integrated process.

    Many enterprise scale operations may find it difficult to flex their muscles around content silos, however smaller organizations can reset their processes faster and see the benefits.

Comments are closed.