Search results

Technical Writing Trends and Predictions for 2017

by Tom Johnson on Jan 28, 2017
categories: api-doc • technical-writing

My 2016 technical writing trends/predictions turned out to be pretty accurate. For 2017 technical writing trends, I'm predicting that more technical writers turn to Github in their documentation workflows. This trend applies mainly to companies where programming technical writers work with engineers to create developer documentation.

Before jumping into trends for 2017, let me briefly review how my 2016 trends predictions turned out.

In 2016, I based my trends predictions off of the rapid growth of REST APIs. Based on API growth, I outlined 10 ripple effects that would extend to technical writers.

1. Use of Swagger with API docs becomes an expectation (2016)

The most popular 3 posts on my site during 2016 were all Swagger related, with the Swagger tutorial taking the number one spot and driving a massive uptake in traffic to my site. So I’d say yes, Swagger continued its upward trajectory in 2016.

2. Markdown as an authoring format gets taken more seriously by the tech comm community (2016)

With Github’s integration of Markdown (including auto-builds with Jekyll site through Github Pages), Markdown has continued to proliferate as the dominant syntax for documentation among developers. More tools support Markdown out of the box, and developers find Markdown natural and easy for their use simple doc needs.

Selling developers on any other syntax (even rST, with all the semantic benefits it offers) is increasingly difficult. In a recent STC Silivon Valley presentation, Andrew Etter noted he has to constantly explain to developers why they use rST instead of Markdown. (See Recording: Modern Technical Writing, by Andrew Etter for details – jump to the 51 minute mark for the relevant commentary on Markdown versus rST/AsciiDoc.)

3. Github as a collaboration platform rises in popularity among tech writers (2016)

Github has continued to become the go-to platform for open source development projects. Teams are not only managing code on Github, but documentation as well. It makes sense to use the same platform for managing documentation as you do code, treating code and doc with similar workflows. (See Adam Wood’s recent post, Docs as code, for more details.)

In an insightful post about 2016 trends, Shaun McCance, who runs Open Help conferences, outlines the top 5 trends in open source documentation. He names Git, lightweight languages, static site generators, continuous integration, and hosted documentation services as trends. Github encompasses all of these features in one platform and workflow.

4. Write the Docs meetup groups proliferate over STC (2016)

Write the Docs continued to gain momentum during 2016. In Eric Holscher’s 2016 Year in Review, Eric mentions thriving statistics for the conferences, Slack group, meetups, and even podcast. Write the Docs is on an upward trajectory and will continue to gain popularity, while the paid membership model of the STC remains stagnant.

Perhaps most important is the Write the Docs Slack group, which has become the technical writer’s watercooler on the Internet, replacing other social media spaces, such as Twitter, for tech writers.

5. Security paranoia forces authentication of docs (2016)

2016 saw numerous scandals with security, from Yahoo’s implosion with millions of hacked accounts, political information from the DNC leaked, “misinformation hacks” from Russia (if they can be considered hacks), and more. Nevertheless, I haven’t noticed any particular trends in the authentication of docs (except maybe this Documentation behind a login thread on Techwhirl). I don’t have a lot of data about authenticated docs, though.

6. Tech writers explore non-traditional tools instead of HATs (2016)

Many tech writers are starting to work with static site generators such as Jekyll, Sphinx, and Middleman. Additionally, some developers choose to build their own custom documentation sites.

It’s hard to find data measuring how many doc teams are migrating away from HATs and other traditional tech comm tools to static site generators. I think in API documentation spaces, static site generators continue to proliferate, especially as developers and UX engineers define the tooling. In other spaces, my feeling is that traditional doc tools remain the norm.

7. Technical writers create more tutorials (instead of just tasks) (2016)

It’s hard to evaluate the popularity of “tutorials.” Certainly the Hello World tutorial continues to be a core topic in developer documentation. The search for “Swagger tutorial” brought a lot of traffic to my site. Additionally, with the Jekyll docs, they will be adding a “Tutorials” category (stored in a collection unique from docs).

When I look at Google trends for “tutorials”, it shows a slow downward slope. I’m not sure how reliable Google Trends is, though.

8. Technical writers study at least one programming language (2016)

In 2016, I had numerous people ask me advice about learning a programming language. I always point them to this post: API doc survey: The most common programming languages tech writers know.

Adam Wood also has a good post on What (and how much) to learn? Udemy has taken off with its array of Nanodegree courses, and more technical writers are hungry to learn development techniques.

Additionally, numerous people went through my API documentation course and found it helpful. For example, David Wilks said, “Tom, this course is great. I’m only part way through it, but it already helped me get a job by appearing fluent in APIs during an interview.” I’ve heard similar feedback from a lot of people this year.

Through this API doc course, technical writers are digging into cURL, JSON, Postman, JavaScript, YAML, the command line, and other common technologies related to REST APIs.

9. Technical writers deliver content via APIs themselves (2016)

This prediction didn’t really play out. Although I listed Contentful as a platform to watch, I haven’t heard anything about content-based APIs in tech comm this year.

Before jumping into predictions for 2017, let me first say that different documentation spaces have different trends. My space is API documentation in Silicon Valley, California. I write documentation for third-party developers creating Android apps.

I’m not entrenched in machinery documentation in Germany. I’m not creating screencasts and instructional learning. I’m not on a team that consists of hundreds of writers. I’m not writing GUI documentation for non-technical end users. I’m not trying to break into the industry as a first-timer. I’m not an XML consultant.

So recognize that my views and perspectives are shaped by my own experience. With that said, here’s what I think is coming for 2017, particularly in developer documentation spaces. Github will emerge as a more common platform for managing and hosting developer documentation.

Here’s why:

Github has come to define the workflow and interaction model that developers follow in collaborating on documentation. Internally, many software shops implement similar models following Git, but without the Github interface. However, I think documentation needs this GUI layer to manage issues, pull requests, doc reviews, and all aspects of the doc process in a more visible, trackable way.

More and more, I’m realizing that documentation is a collaborative effort by communities of people. It isn’t the effort of a single technical writer assigned to a project. The idea that documentation can be perfected by just a few technical writers working outside the business, outside immersion in deep developer tasks, and largely working alone is ludicrous.

The past couple of months, I wanted to become more familiar with open source workflows for docs. So I participated in some documentation edits and additions on the Jekyll site. I thought I’d contributed heavily to some doc improvements, but then I looked at the list of resolved issues in the 3.4.0 release and realized my contributions were a mere drop in the bucket.

There were probably 100+ issues that were surfaced, discussed, resolved, and merged across dozens of different people and teams. A lot of effort goes into running a software project, and seeing the list of doc updates across the site from so many different people humbled me. Even with my contributions, others followed to correct or add to the content that I’d written.

If documentation for any project is going to thrive, it needs the attention and contributions of a whole community of active users.

At my work, we want to embrace a Github workflow. You can already see this Github revolution in other companies with Microsoft and their Azure docs. They shifted away from the cumbersome, slow XML model with MSDN and have reinvented their docs in the community following an open source model.

Definitely listen to this Open Authoring – Collaboration Across Disciplines presentation by Ralph Squillace. Microsoft’s Azure docs embody all the points Shaun mentioned in his 2016 trends. The Azure docs are Markdown-based, generated with static site generators, housed on Github, continuously integrated, and more. They use pull-request workflow for updates – both internal and external. Ralph says the external PRs are mostly minor fixes for typos, but internally engineers across the company contribute significantly to the content.

Solutions architects and business developers tell me that they want docs to be in the same spaces that developers are in. Developers are on Github, Stack Overflow, and more. We want our docs to tap into these communities and integrate into common developer touchpoints. We want to enable developers, field engineers, and others to flag issues with docs, track the progress of submitted issues, and submit pull requests.

Technical writers do not have the bandwidth to author every doc needed for a project. The Github workflow is something developers understand and can easily work with. Technical writers will take on roles where they process pull requests, integrate doc content into the larger site, edit and simplify content, test out instructions to ensure accuracy, and more.

Rather than manage this process through tedious email chains, or by trying to insert yourself into the right meeting, technical writers will do it through Github. To do this, technical writers will need to become masters of the Github workflow. They’ll need to understand how to review pull requests, suggest improvements, clone patches and make edits to those patches, merge branches, run validation tests, automate builds, and more.

In summary, in 2017 and beyond, we’ll see developer documentation start to move to Github as the primary platform for interaction points with developers both inside and outside companies. Documentation won’t likely be published with the plain-jane Github styling. Instead, Github repos will be the source from which documentation will originate in a publishing toolchain.

Remember that I’m just referring to trends with developer docs, such as API documentation. I’m not referring to documentation for non-technical end users, or documentation for airline mechanics or other groups who might not use Github and engineering workflows.

What do you think? Am I on target with my 2017 predictions? Do you foresee problems with this direction?

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson