The Changing Landscape of Technical Writing

The new generation of technical writers is quite often embedded in a team of software developers and QA engineers who espouse agile project management methodologies like Scrum or Kanban and are keen on distributed revision control management systems like Git or Mercurial. These technical writers usually some software coding experience or have taken some computer science classes. Many of them have degrees in literature or one of the humanities. This is what they do full-time. Their employers really value well-written technical documentation and consequently unlike many large corporations in retail or other non-tech industries, do not consider documentation an afterthought, a responsibility to be dumped on software developers who notoriously hate documenting their APIs.

Why do software developers hate documenting their code?

Around 4 minutes into this presentation, Mason Egger explains why: “Most developers don’t dislike writing documentation. What they dislike is the workflow.”

  • A developer has to switch tools when they want to document something (outside of in-code documentation).

  • This context-switch makes them reluctant to write docs, so the task gets pushed off to the very end.

Google adopted a radically new approach to producing their engineering documentation around 2015. Riona MacNamara, who is a staff technical writer at Google and leads their Documentation Infrastructure team provides some history of their g3doc project and how it transformed their engineering documentation in her 2016 presentation, The Knowledge: Towards a Culture of Engineering Documentation. By getting the technical writing team to work more as peers with the software developers and not alienate them with special documentation writing software, the developers soon were documenting their code in Markdown and having fun doing it, because they could use the same tools they use for writing code.

The Opposing Methodologies: Old School versus New School

In the world of technical writing in 2019 there are two competing methodologies which have diametrically opposed ideas about how to achieve the same goal: producing quality, technical documentation. Statistics are hard to get on which of these two philosophies is most popular with technical writers:

  1. New School: The lean, markup-based, text-only approach, that allows technical writers to focus on what technical writers do: write documentation! The new philosophy is a radical departure from Old School tools that force writers to break their concentration on creating content by having to grab for a mouse to highlight text for formatting and then search through dozens of formatting icons on multiple rows with confusing menus in an attempt to find the right type of formatting needed.

    The new crop of technical writers who openly promote this workflow of creating plain-text content using a standardized markup language like AsciiDoc (or reStructedText, Markdown, LaTeX, etc.), and then committing each revision this content to a source code control system like Git, where colleagues can view the differences with the previous version, provide comments, suggestions, and collaborate. Compare this to my preferred set of tools.

    It is true that most of the New School technical writers work mainly on software documentation (more back-end, like APIs, than front-end), however, there is nothing preventing this workflow using these tools from being deployed on projects in other industries. I used LaTeX, used mainly for texts with a main focus on higher mathematics, to produce a entire book in a series on (German language) Swabian Literature.

    At the end of the day, being able to automatically compile the markup into high performance, hugely scalable, static html sites for either internal collaboration or for final public-facing consumption is a huge win over the Old School approach.

    With little or no effort the markup files can be exported as PDFs or practically any other format that might be needed for post-processing or print publishing.

  2. Old School: The mindset of this group is that costly, proprietary, anti-markup, DTP-style, WYSIWYG applications that have been retooled to add client-server architecture, and collaborative functionality are the only tools needed to produce quality documentation. Oddly enough, this group is the least likely to hire full-time, technical writers to produce that product.

    Adobe InDesign is a classic example of a revamped DTP application that is geared more towards typography for high gloss brochures rather than functional API documentation to be made available to customers seeking timely information via the web. How many software developers document their APIs know or care about recto versus verso, have a clue about kerning or what a ligature is?

    A similar application would be Microsoft Publisher, however, the shop that skimps on full-time technical writers is not likely to pay for Microsoft Publisher when they can use Microsoft Word documents instead. For this kind of shop, Word documents are likely to shared via any of the Microsoft collaborative ecosystems: Teams, SharePoint, etc.

    Other applications or SaaS offerings like Confluence by Atlassian are designed to be used as internal tools for cross-team collaboration where neither printed matter, e-books, nor downloadable PDFs are the primary medium of consumption. Confluence has the following limitations:

    • Two pages cannot have the same title within the same namespace, even if they have different parents. This could prove awkward if Confluence is intended for documentation having repetitive titles.

    • There is no standard way of adding captions to images, there are only workarounds.

    • There are certain bugs in editing that makes it very unreliable tool. If you refresh during editing your data will be lost. Subheadings of level 3 are impossible to edit using the local edit button.