Tuesday, 30 August 2016

Are Technical Writers Becoming Obsolete?

When I started working in the software industry just after the turn of the century, there were Technical Writers, Document Authors and occasionally - just to spice things up a bit - Technical Authors.  All 3 of these roles did the same thing: write end user documentation that would either be printed or displayed on screen in a help format like CHM.  This documentation was aimed either at people who installed, configured and administered the software, or at users who had to navigate the UI on a daily basis to do their job.

Nowadays, every part of that has changed.  We have Information Architects, Knowledge Engineers, Content Strategists, UX Writers and "Document Wranglers" (no, me neither).  All of these roles seem to do different things, and none of them seem to have writing good old-fashioned help documentation as their primary role.  End user documentation seems to have become very passée, with little love left for a large body of writing that explains how something works. The notion of putting documentation into a .chm is scoffed at; the notion of providing a printed copy is as old-fashioned as the idea of burning your DevOps maven because she might be a witch.

Some of these changes are driven by technology.  With many applications being solely or largely online, it makes no sense to provide a .chm when a .chm is essentially just HTML, CSS and JavaScript.  There's a better, faster, more open delivery mechanism for that, and it's called a web page. On that note, as dial-up has gone the way of the phone box, there's no need to send customers the help file on a CD or on actual paper through the post.  People can download a 500 page 10mb document in a couple of seconds, although the irony is that as the documentation is delivered online using topic-based authoring, they can pick and choose what they want to see so they'd never need the whole documentation stack anyway. 

Likewise, the explosion of mobile apps and the sudden realisation that yes, good UX design IS ACTUALLY IMPORTANT (a fact that many, many companies seem to have been oblivious to pre-smart phone) has meant that a lot of small companies are letting their design do the communication for them, and the absolute minimal documentation required is in the form of prompts, labels and warnings.  These are done, if anyone does them formally, by the UX designer or a dev who's more interested or more junior than the other devs.  The mobile apps created by big companies have also forced them to realise the importance and value of good UX design, but unfortunately the completely expected has then happened: "Ooh, we didn't need a technical writer for our new mobile app because of the great design.  Let's apply that principle to our enterprise application and we can save on writers!" (This is despite the fact that their 20-million-lines-of-code enterprise application is lugging around years of technical debt and is so poorly designed that the idea of making it lightweight enough to go online is a running joke amongst the devs.  But sure, get rid of your writers, that's the problem you need to solve.)

And some of these changes have come about because it's now easier to automate some of the writer's job.  If you set up Swagger with the right templates and show a little care, your API documentation, or at least the core of it, can be provided at the press of a button.  Provide your Confluence users with well-thought out templates with mandatory fields and macros linked to JIRA, and your release documentation can be written by anyone in your team.  I would never say that these thing are enough (and I'll believe that to my dying day) but the cost-benefit ratio of hiring a dedicated writer changes with each new automation technology that chips away at the periphery of what the writer does.

However, some of these changes to the writer function are driven by methodology.  In an agile world - and if you're not agile you're very out-of-step with modernity, no matter what you think about it - the specialist is a dying and unwanted breed. No-one can be "just" a writer any more, because what we do often doesn't exist in any meaningful way now. Sure, there are plenty of massive enterprise level applications out there that need equally massive help files, but these are becoming the exception rather than the rule.  This is not helped by disruption on a grand scale from start-ups that value doing one thing really well, and a clientele of millennials who are starting to reach an age where they an have an input into buying decisions, and who are not bothered in the slightest by the idea of buying 10 different apps and using IFTTT to fit them together, rather than spending 20x as much on a behemoth from a 50 years old blue chip. 

With everyone moving to agile, the expectation is that the specialist writer can no longer be siloed into "just" writing documentation.  Hence a role like Knowledge Engineer, where you conduct the fragmentary topics to the right place to form a coherent orchestra for your audience, or Content Strategist, where you act as a lode stone to keep all of the disparate documents from different experts pointing in the same direction.  In many cases it is no longer enough to be able to write; you must be able to plan, build, guide, persuade, manage.  Writing in and of itself is almost secondary.

If you look at the coalescing of the following trends:

  • Mobile apps;
  • Better UX investment;
  • More documentation automation tools;
  • Fragmented market of smaller providers;
  • Move to "specialised generalists" in agile.
Then you'll see that none of them are positive for the working prospects of a "pure" technical writer. It may seem that the pure skill of a technical writer - writing - is less valued than it was before, but the companies that valued this before will still value it now.  It's the changing of the technologies and methodologies that are allowing companies that never really valued documentation to do away with technical writers, and new companies that join the fray don't see the cost-benefit ratio of having a technical writer in the first place.  They hire a Content Strategist to provide a guiding strategy and write some templates, add documentation (using Swagger and other tools) to the Definition of Done, and have a Knowledge Manager to look after the internal wiki and provide light editing of the docs.  They release updates several times a week so there's plenty of scope to iteratively improve the docs as they go.  And that's it.  Where does the technical writer fit into that?  Answer: They don't.  


So where do you go if you're a technical writer?  Do you transition to analysis, QA, testing, product management, training, support, or move to a different industry altogether?  Do you keep chasing the ever-decreasing number of "pure" technical writing jobs?  Do you specialise in API and/or SDK documentation on the basis that it's one of the few areas where there aren't enough qualified writers to fill the all the vacancies?  All of these are valid and sensible options.  In the long run though, you're best off learning how to do all of the things that have been chipped away.  Learn how to use Swagger and other documentation automation tools.  Learn how text is displayed in your application and become its writer, editor and proofreader.  Learn at least the basics of UX design and join the discussions about how best to show - rather than tell - the user what to do next (because no-one is better than you at understanding that).  Become a moderator for forums that discuss your company and its products.  Learn how to manage the knowledge assets your company has.  Learn what a content strategy is and create one.  


Because being a Technical Writer is no longer enough in a lot of companies.  Eventually it won't be enough in any company.