Life in docs 2018 survey — Part 1: Results

David Ryan
Aug 17, 2018 · 10 min read

What is the life of a technical writer like in 2018? This is a question I asked earlier in the year. And you replied.

When I announced that I did so to push ourselves further in our journey towards . And also to encourage us all to check in on our industry and culture more regularly. So to that end I say thank you to everyone that participated — as a personal note I really appreciate the honesty and effort put into your answers.

As we’re about to see, the morale in technical writing is surprisingly high. But so are the challenges facing teams shifting increasingly towards constant change. In structure, in product, and even in workflows and our very identity as content professionals. Let’s take a look.

A Note on data

The following is a narrative analysis of the results. An easy way to read this is to skip through the graphs and dig into the insights in whatever question you find most interesting. I suggest for your own analysis. And then moving on to for a deep dive into what this data all means.

Overall we were aiming for 100 replies to the survey — intending to run them regularly (hence the qualitative questions). We received 333 replies of which only 16% were 👻 anonymous.

Q1. What is your role?

Here we see the vast majority of replies self identifying as writers. This is expected in a technical writing survey — so the interesting thing is the other roles that have chosen to participate.

The “other” category consists of a mix of content strategy, information architecture, design, content management and similar roles. This also indicates the broadening of the role beyond the era of just “writing documentation”, with customer content teams exploring video, social assets, control infrastructure and design, etc.

Q2. What do you love most about the job?

As a free text answer we can interpret the results a number of ways. Here’s a word cloud to give the unsurprising view that writers like writing. Note that “documentation” is in a relatively minor position.

What can be appreciated is the prevalence of “product”, “people” and “helping”. Reading the source replies we can get a feel for the genuine desire to learn and to be helpful to users. It’s worth reminding that this isn’t a job interview — it’s an anonymous community survey. They mean what they write.

Notable responses

  • “Learning new ways to make content easy to access and read.”
  • “Seeing other people’s pain points and then writing something or building something that will help them.”
  • “Learning new things and knowing the stuff you write helps people.”
  • “Flexibility to work with a wide range of SME’s and stake holders.”
  • “Supporting our customers to make the most of our products.”
  • “The challenge. The people. The knowledge that we’re working on products that make a difference. The free snacks don’t hurt, either.”

The source data is mandatory reading for a team leader or management looking to understand the motivations of their team. There’s a lot more going on here than just “writing”. It might be time to look around at writing team a little differently.

Q3. What do you dislike the most about the job?

If there’s one thing that technical writing mailing lists have been good at in the last decade it’s being disgruntled. Let’s see how that holds up.

Okay the word cloud isn’t particularly useful here as the descriptions of frustrations get quite specific. Let’s dive in to some of those.

Notable responses

  • “Hype amongst writers to write for themselves rather than for users.”
  • “Convincing people that docs matter.”
  • “I can be socially isolated.”
  • “The complete lack of understanding by hiring managers and project managers of a realistic timeline to accomplish the necessary content.”
  • “Co-workers don’t really understand what I do or why.”
  • “Struggling to find the right tools.”

Rather than being an angry outpouring about the confronting changes in the industry, the majority of replies suggested a more personal reflection.

Writers feel that their’s is often an undervalued and misunderstood role. It’s difficult for writers to point to examples of value without access to breakout case studies of content team wins. We’ll dig into this idea more in the summary section.

4. What are the main content tools that you create content with?

This question allowed the replies to described the core tools that writers identify as a meaningful part of their workflow. Listing the top 20 products or services reported shows a trend that will look familiar.

Breaking this down into specific writing tools illustrates the dominance of Microsoft Word as an incumbent. The continuing rise of the cloud is evident in the relative rise of Google Docs.

It’s interesting to see a number of XML tools in this representation. While the format itself is in decline, the remaining vendors are competing for what is still a large legacy user base.

Adobe is as to be expected here (especially given their advertising blitz in the technical writing space — despite declining revenues across their publishing range that they admit is a “” interest). This accounts for Atlassian’s Confluence and MadCap’s Flare continuing their push into this market.

5. What are the main outputs that you publish to?

The intention behind the free text answer here is to capture the range of replies in their own words. This gives context to the rapidly changing requirements for delivering content in forms that users require. As well as understanding the culture of content publishing. Even if that involves a lot more PDF than we might perhaps desire.

These answers aren’t a definitive analysis of what we are actually outputting, but a view into the formats we are most focused on. This topic is a critical one for it’s own survey at depth. Especially as we are yet to fully respond to the impact of the ubiquity of mobile devices and related emphasis on UX and user-centric re-engineering of our publishing endpoints.

Notable replies

  • “PDF for the vast majority of projects. These files are usually hosted online and either viewed on screens or printed later by users as needed.”
  • “Confluence and Google Slides for internal audiences on highly technical or confidential information.”
  • “PDFs are posted on our website in a secure area that requires registration and approval.”
  • “A custom micro-CMS built into our core product.”
  • “The assets I do create are stored on the companies gDrive, with some duplication in Confluence & JIRA.”
  • “These are posted to SharePoint or to Dropbox or both. The HTML5/CHM content is also posted on the development server for inclusion in the latest release package.”

Each of these replies indicates an interesting scenario that raise more questions about workflow, legacy processes, and user journeys.

6. How happy are you with this workflow?

The majority of replies were largely happy with the content workflow. While such an NPS-style question does suffer from “” of rating out of ten, it does give a quick mood check in the context of the overall conversation about technical writing life.

Here’s another view of the mood around workflow. The interesting conversations are those at either extreme — the 23 people who rated their workflow between 1 and 3, as well as the 11 people who rated their workflow a 10. What’s so bad? What’s going so great? There are lessons to be learned from each.

From a team leadership point of view these extremes are a focus for productivity and happiness. The low ratings indicate frustration in tools, process or culture that are affecting a team member — important both to the human as to their output. On the other extreme are useful observations to replicate and celebrate.

7. If you could make this workflow easier, what would that look like?

These results show a mix of frustration and genuine commitment to improvement. A common theme is for a workflow to make the process more consistent and less manual. And a large emphasis on collaboration.

Notable replies

  • “Fewer items that have to be done by hand every time there’s an update.”
  • “The technical team (developers) would be more actively involved from the start. Currently they are reactive rather than proactive.”
  • “Enforce documentation process throughout teams, make sure the same process is followed so documentation is easier to use across different teams.”
  • “I would like to see more interaction between tech writers and users.”
  • “Authoring tool that works with chunks/source-content management , and generates HTML directly.”
  • “Provide users with options instead of all text based answers.”

We see the familiar challenges of improving overly manual toolchains and creating a standard for their use. What’s interesting is the increasing theme of the desire to increase collaboration internally and increase access to external users. And then to supply those users with content in whatever format or via whatever channel would be most effective in solving their needs.

8. Do you find it easy to get others to collaborate on what you’re working on?

At a glance we can see that the community is largely happy with the ease of collaboration.

At this level we don’t have any insight into the demographic here — such as the type of organisational structure and size of the organisation. This question is still useful as a mood check and heat map for future surveys. It would also make a useful metric to measure and track over time.

9. How would you improve that collaboration?

Replies to this question are often either surprisingly detailed, or wonderfully precise in their brevity. With in the workplace, it’s no surprise that content teams are ready with ideas.

Notable replies

  • “Proper integration of tech writing in the development projects, make devs co-responsible for production of tech publications such as user guides and API doc.”
  • “Make the writing a priority and not the last and least thought before the next version of the application is published.”
  • “Collaboration tools should not be dependant on the product in which the documents are created.”
  • “It would be helpful if more internal people embraced the technologies made available to facilitate team meetings and collaboration.”
  • “Understanding of the process and need for whole team approach — I cannot write about nothing!”
  • “Get more proactive and be involved in all the relevant engineering and project meetings so you are abreast of the release schedule.”

A lot of replies requested better feedback and inclusion in the bigger picture. With writers keen to make an impact, eager to move away of feelings of isolation, and with a genuine perspective on the macro view of how a product is used — this is a an opportunity to take a more proactive role in collaboration. And one the industry seems willing to undertake.

10. Anything else you would like to share about technical writing in 2018?

The replies to this question are worth downloading the source data alone. The themes range across the trend we can see in a desire for inclusion, aspirations of greater collaboration and respect among the team.

There are also some interesting regional comments, as well as a reminder that diversity of background and age and experience is a positive thing.

Notable replies

  • “We need to continue to educate ourselves on technologies and adding marketable skills to our resumes.”
  • “The changing landscape of technology and new generation of users means there is a constant challenge to convey even more information, presented in more engaging formats, in more universally accepted language and style. It’s a great challenge.”
  • “It’s all product marketing — tech writers need to own that.”
  • “This is still a sometimes disrespected role. Many people have no concept of what this job really entails. They expect me to have ESP or to absorb information by osmosis since they haven’t told me what I need to know.”
  • “On collaboration, we as a profession should be networking more with other types of business writers to raise our profile.”
  • “Age shouldn’t matter. Older writers can and do love to learn new things.”
  • “Tech writers of the world unite! :)”


11. We’ll send you the results. What’s your email?

A surprising 84% of replies included an email address. This is far greater than expected and a positive indication of the industry’s attitude towards collaboration and improvement.

That’s it for the survey data. Now lets work out what all of this means (and what we can do about it). Clap your love for this post and then click the link below.

My name is , the creator of , a collaborative documentation tool for software teams. All about PM and UX and content team collaboration. Formerly and the . How can I help?

Corilla Blog

Notes on technical writing and the future of content by the Corilla team and community.

David Ryan

Written by

All about PM and UX and open source. Formerly Red Hat and Corilla.

Corilla Blog

Notes on technical writing and the future of content by the Corilla team and community.