If you have been following this blog, you will realize we have covered several of the most commonly discussed aspects of the technical writing profession: what the technical writing profession is about, and how to become a technical writer.
In this article, we want to talk about something that is often the least pronounced theme during discussions around the technical writing profession: the duties of a technical writer.
You are right to think the duties of a technical writer are implied in much of the discussions around what a technical writer is, which might answer why it is not the most pronounced during a conversation about technical writing. However, we think there are certain nuances to the technical writing profession that is only visible when the profession is discussed from the perspective of defining a technical writer by their duties.
Perspectives help to add richness to existing knowledge about a subject and we intend to do that to help you gain more profound knowledge of the technical profession.
Aside from helping you become a better technical writer, discussing the duties is important because most job descriptions always include a section that highlights the roles or duties of the technical writer to be hired.
These duties often range from job to job, and could even be a little daunting when faced with certain job descriptions that come off as way too demanding in the expected duties of the technical writer. But the point here is, these variations could blur focus away from your core duties as a technical writer, and we don’t think that should be the case.
So, in this article, we would be discussing the core duties you have as a technical writer.
Duties of a Technical Writer
Technical writers are user advocates. This is your primary duty as a technical writer.
As a technical writer, you represent the users in the company. The interests of the users must always be the thrust of all your technical writing works.
As a user advocate, you are expected to ensure the documentation you create is transparent. You must demonstrate empathy in creating all your documentation content by anticipating users’ needs and acting accordingly to ensure those needs are met.
Is the product lacking a feature end users expect the product to have? Then, you should mention it in the documentation, so users are aware and factor it in making decisions on the product.
Are there any limitations, or issues with the current release of the product? Then, the documentation should mention it even if the issue will be fixed in the next product release.
In other words, you are to help the users see the product in the clearest light possible. No information on the product must be left in the dark.
This duty should not be treated with levity, as it could occasionally lead you down uncomfortable paths. This occurs if it conflicts with the interests of other significant parties, for instance, the product or marketing managers.
The product or marketing managers’ main interest is to present the product in an extremely positive light. In instances, where mentioning product issues or limitations results in a conflict of interest, then you might be up against some significant persons with more control and power than you are. It is important you handle the case with gentility and empathy while demonstrating good communication in finding a compromise.
It is important to understand first that such objections are usually motivated by the fear that mentioning product issues and limitations in the documentation taint the product with negativity, which is believed would drive away users.
To appease this, you might try helping the product manager understand that failing to mention the product limitations could prove even more costly, especially if users have to discover those limitations themselves.
You could also try citing factual examples, such as mentions of limitations in other documentation you’ve worked on which had not resulted in any significant loss of users. Here, what you are trying to do is to find a compromise that appeals to the interest of the product or marketing manager.
It is important to note that in finding such a compromise, you could err on your duty to be as transparent as possible in your documentation content. In such scenarios, Tom Johnson, a lead technical writer, says this:
Although traditionally as a technical writer you don’t run into too many ethical scenarios for docs, sometimes you have situations where your ability to be transparent about a system’s limitations gets curtailed by marketing or product management. It can be frustrating to have your documentation filtered like this, but you can take comfort knowing that, given the decentralized nature of information on the web, where any user can post information in forums, blogs, and other sites, the information filtered out of your docs will eventually be published online (it just might not be published by you).Tom Johnson
Technical Communication and Accuracy
It is no coincidence that technical writing is often called technical communication, which I would think is a good term for describing the duties of the technical writer.
You want to ensure you are technically accurate in the documentation; and that you are articulate in communicating a product or feature, connecting the dots and providing a single source of truth or a single reference point on every aspect of the product.
This is where comprehensiveness, updating documentation, customer support tickets, and community forums (especially, around the product) comes into play.
Users post remarks and complaints about their pain points on community forums. They also submit tickets to the company and customer service in order to air their pain points. All these help you discover content gaps in that documentation that needs to be covered.
So you want to ensure you have a standard process established for updating the documentation so that it maintains quality with each documentation release.
Keeping the documentation updated and comprehensive might entail many moving parts like keeping UI images used in the documentation in sync with changes in the UI of the product, keeping the API reference documentation up to date, and so on.
A good way to handle this is by using automation tools such as static site generators and screenshot automation tools to handle these workflows.
Aside from ensuring the technical accuracy of documentation, you also want to develop your intuitive ability to stack information in a way that aligns with user needs to ensure easy accessibility.
You want to keep the most used documentation content at the top of the hierarchy, and the less consulted ones closer to the bottom of the hierarchy.
You don’t want to place the installation guides or the getting started tutorials at the bottom of the hierarchy, and the release notes at the top of the hierarchy. That would be bad information architecture.
One good documentation framework that could provide you with an easy template for providing a good information architecture for your documentation is Danielle Procida’s Diataxis framework.
You could use our blog content on each of the four quadrants to help you gain an in-depth understanding of each of the quadrants, their use cases, and what differentiates them from each other.
As a technical writer, dispensing your roles, especially as it relates to writing, reviewing, and publishing documentation will require you to move in-between many teams and departments, most commonly, the engineering team, product team, and quality assurance team.
You will be collaborating and communicating with appointed individuals from each team to create documentation.
This is more of a requirement in dispensing your duties than a duty in itself. So this implies, you need to develop your collaboration and communication skills so you can engage productively with the teams you need to work with to create documentation.
So those are the duties you have as a technical writer. It should be noted that your duties are quite different from the content you create, say, tutorials or how-to guides; and it is also different from various specific tasks you perform as a technical writer.
Your duties as a technical writer are the umbrella under which all your specific tasks fall, and it is expected that you tailor each of them to align with your duties.
So that’s it for this article. Hope you learned something. Leave comments and give a like if you love the blog post.