Illustrating the multifaceted role of a tech writer

After a few conversations with various people, I decided that it may be useful to have an illustration of the multifaceted role of a tech writer. In particular, many of our stakeholders (product teams, engineering teams, marketing teams, etc) may not know all the ins and outs of what we do. A handy illustration may help conversations with product teams and other stakeholders.

Many people see our role as being focused on documenting the features of a product:

Here’s an illustration of the tech writing role, de-emphasizing the feature docs part of the role:

The many aspects of a tech writer’s role:

  • Gather the information required to develop the docs. Some ways to gather information: interview engineers, product managers, etc; read the code; read the product requirements document and other specifications; experiment with the product.
  • Analyse and define the audience.
  • Analyse the most common tasks and workflows of the target users.
  • Design the structure of the docs as a whole (information architecture).
  • Own the user experience (UX) of the docs: consistency; findability, readability, accessibility.
  • Ensure consistency with the product user interface (UI).
  • Ensure cross-product consistency, that is, consistency with the docs of related products: tone, terminology, coverage.
  • Review doc updates from other technical writers, engineers, and community contributors.
  • Stand up for the customer and give UX advice, as the first-time user of the product.
  • Create conceptual guides that explain the product at a high level, for new starters, and that explain the principles and details behind the product design and functionality, for people who want a deep dive into a particular technology.
  • Create getting-started guides covering the primary product features.
  • Create end-to-end tutorials, each covering a use case that involves multiple features.

Some technical writers have an even broader purview, depending on the team and the doc set they’re working with. For example, if the doc set is hosted on a self-managed website as opposed to a corporate website with shared infrastructure, the tech writer often takes on website design and management tasks. Small teams may not have software engineers available to create code samples, and so the tech writer creates those too. Open source docs in particular bring additional responsibilities.

Here are some of the additional tasks a tech writer may take on:

  • Develop illustrative code samples to include in the documentation.
  • Develop training material.
  • Produce videos, either as training material or as illustrative material to supplement or even replace the documentation.
  • Own the design and infrastructure of the documentation website: look and feel (theme), site search, version control, navigation aids, etc.
  • For open source products, educate and encourage the community to contribute to the docs.
  • Manage the repository that holds the documentation source files.

FYI, I based the above diagram on one that’s often used in presentations about machine learning (ML) to show the relatively small part of the ML workflow that’s devoted to actually writing the ML code. The original ML diagram is in this paper.

What do you think?

Does this diagram present an interesting way of starting a conversation about the role of a tech writer? I’d love to hear your thoughts and ideas!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 1 April 2019, in technical writing and tagged , , . Bookmark the permalink. 12 Comments.

  1. A great summary, which should be illuminating for many. Unfortunately some of them may assume it’s related to April Fool’s Day.

    • Thanks. It isn’t related to April Fool’s Day. I actually published the post on March 31 (I’m in the UK), although the WordPress time stamp is April 1 due to the blog’s time zone. Luckily the post doesn’t have the tone or over-the-top content of a typical April Fool’s prank. I haven’t seen any comments on social media that may indicate confusion.

  2. Very well portrayed Sarah. The ownership of the product documentation technical writers take definitely needs lots of, say behind the scenes work, that is not transparent to other Teams. To add few more aspects:
    * Testing – Logging in and testing the product to validate the instructions and screens
    * Publishing – Separate workflows to be followed for various authoring tools. GitHub for instance, sometimes requires running Python scripts to publish the content unless automated by the admins
    * Running through the code – Required to understand features well before documenting the features or functions. API documentation

    • Hallo Altaf
      Thanks for those additions! It’s great to see more aspects of our role. Jim Travis added another on Twitter: “engaging directly with customers, growing customer love for the product”.
      Cheers
      Sarah

  3. Managing the translation of the docs is another big task. A few people have mentioned it on various channels in response to this post. Thanks all!

  4. Alison Turner

    A good summary. I’d add testing the product UI and trailing potential product developments by trying to document features before they are implemented

    • Hallo Alison
      Thanks! I like your point about attempting to document features before they’re implemented. It’s a challenge. On the one hand, we need to get the docs out on time and so we often need to start the documentation before the feature is available for our use. On the other hand, we may end up writing incorrect content, as the implementation may differ from the original plan due to real-world constraints. Tech writing as fiction. 😉
      Cheers
      Sarah

  5. I agree with all of the points, but I would also include a pivotal role between R&D and Regulatory Affairs. You can write a really good document, but the product may not get regulatory approval if the documentation doesn’t tick all of the reviewing body’s boxes! That is where I excel as a TA, because I can critique ISO standards and make sure that all of the applicable ones are satisfied. Not just ISO 26514, but every one that pertains to the product, its manufacture, its environment, its Health and Safety, and even its global markets.

    • Hallo John
      That’s a good point. It ties in with the fact that tech writing is a wide field in terms of the industries we work in, as well as the tasks we perform. Not all tech writers need to deal with compliance to regulations, so it’s good to have your reminder.
      Cheers
      Sarah

  6. Good article. I like seeing this information visually and think it’s spot on!

  7. Lisa Lambert

    Hi Sarah,
    Would you consider developing this into a 1 hour presentation? I am the conference coordinator for CIDM. We have 4 events per year x 21 years! We host the Content Management Strategies/DITA Conference, The Best Practices Management Conference and the IDEAS Online Conference.

    The next IDEAS conference theme is : The Many Hats of a Technical Communicator — July 23-24, 2019 and your subject fits perfectly! If you’re interested, please visit the link below, to let me know: https://ideas.infomanagementcenter.com/call-for-speakers-summer-2019/
    (please disregard the deadlines shown on this page, which have already passed.)

    Please let me know if you would be interested,,
    Lisa

    Lisa Lambert
    Conference Coordinator
    303-232-7586

    Join The Center for Information-Development Management at the following conferences:
    CMS/DITA North America held April 15-17, 2019. More Information: https://cm-strategies.com
    The Best Practices Conference held September 9-11, 2019. More Information: https://bp.infomanagementcenter.com

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: