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:

[image error]

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

[image error]

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!