Why do you need a Technical Writer?

Before we bring technical writers into the picture, let’s imagine this scenario:

What if we didn’t write documentation at all?

This seems odd, but when you think about it, that’s exactly how companies usually start.

Stage 1: No documentation

Imagine that you create a company and start to develop a product. For example, a website for people to write posts. You are focused on developing new features, and documentation is the least of your concerns. Your product is so simple that everything seems obvious, and there’s always that one person that knows how your product works (every company has that person).

As your company grows, your website becomes more complex, containing a lot of new features. You start to get users but they don’t really understand how to, for example, publish posts, and don’t feel comfortable using it (yes, users are like that).

Also, remember that person that knew everything about your product? That person is leaving the company and no one really knows how the website works.

What do you do now? You will probably (or should!) start to document your product.

Stage 2: You have documentation but no technical writer yet

When you first realize that you need documentation, the job is usually given to the closest person to the product, most likely, a developer. By having documentation written by developers, you ensure its technical accuracy and that it describes exactly what the product does. Also, as teams control their own work, you won’t have a development bottleneck.

However, since developers naturally focus on the technical side of a feature, documentation becomes too technical and not very user-friendly. This may not be a big issue if you are doing, for example, API documentation, but if you want to include tutorials on how to publish posts or more functional content, your users may not be happy with your documentation deliverables.

Finally, the most obvious issue: most developers don’t like to write documentation and consider it an unpleasant task. And you don’t want unhappy developers, right?

So what do you do to solve this? How do you keep your users and your team happy?

It’s time to move to the next stage: you need a technical writer.

Stage 3: You have documentation and one technical writer

A technical writer is someone whose main task is to simplify technical content without losing the technical accuracy.

By having a technical writer, you have a person fully focused on documenting your website. This way, developers can focus on coding cool features while the technical writer takes care of docs. This doesn’t mean that developers don’t have to produce documentation. The technical writer’s main focus should be user-oriented documentation and not documentation for internal use. For example, when writing a highly technical document such as a third-party integration guide, developers know all the process specifics and can explain them better than anyone.

Having a technical writer will also provide higher quality documentation when it comes to grammar and consistency — not just for an individual document but for all the company documents. Lastly and (probably) the most important advantage: you have a user advocate. This means that you have someone that is focused on understanding your users’ pains, challenges and needs, and your product’s documentation will definitely reflect that.

However, having a technical writer may affect a team’s dynamic. For a technical writer to produce quality documentation, developers and technical writers have to join forces and work together. Developers have a deep knowledge on one particular thing (or set of things) while technical writers have a surface knowledge about many things. So, developers need to share their deep knowledge so that the technical writer can learn and then transmit it to your users.

As teams begin to recognize the role and relevance of a technical writer, more tasks and projects start to appear: tooling, visual content, training materials, knowledge sharing, copywriting, curation, maintenance… The list goes on. As workload increases, a technical writer can become the bottleneck of the release and nobody wants that. Since one technical writer can’t do all the work, you have two options: change the scope of the documentation project or hire more technical writers.

So, how do you keep your technical writer sane and your company going regarding documentation? You hire more technical writers and start building a team.

Stage 4: You have documentation and a team of technical writers

This is a rare stage, as there aren’t many companies that actually reach it.

The first step is to hire new team members — AKA technical writers. When you start hiring people for your team, you don’t really have a measurement to compare candidates and understand why one person suits your team better than another person. What qualities and skills are you looking for? It’s easy to assume that someone coming from a linguistics background is the right choice, but maybe your product is so complex that you’ll need someone with a more techy profile. How do you show that your company has an established plan for the technical writing team in a way that makes sense for the candidates?

Starting a technical writing team means that you have to show its worth really, really fast. You will probably need to take on a high-visibility project and show how technical writers can improve documentation consistency, process and overall quality. However, usually, companies don’t have a culture for technical documentation from the get-go. In fact, companies may assume that the technical writing team will perform tasks such as writing job descriptions or sales and marketing content. Technical writers can definitely help out with these tasks, but this should not be their main focus. Also, having a technical writing team creates the wrong idea and expectation that developers will never need to write documentation at all. Again, this couldn’t be further from the truth. Of course it’s not their main mission, but developers still have to write documentation as it’s part of a software engineer’s job description.

Finally, at this stage (and even on more advanced stages), the ratio between technical writers and developers is very, very low and the technical writing team cannot undertake all documentation tasks at once. In addition, growing companies tend to focus on the tech side of the product, and the technical writing team does not grow at the same scale. Either way, the technical writing team is always playing catch-up.

Stage 5: What’s next?

After you’ve established a team, how do you evolve it?

At Feedzai, we currently have 7 technical communicators distributed across different product clusters. Yes, I said communicators. We recently changed our team’s name to Tech Comms because we do much more than just writing, and this has also changed our own mindset to be more open to new challenges within the company.

As Nuno Grazina explained in this post:

The untrained eye might have trouble telling them apart, but if you are trying to get a “that guy who writes”, you won’t find a technical communicator. If you are looking for a technical writer, you’ll find a “that guy who writes”.

Our Tech Comms team creates documentation for product features, produces training materials and visual elements, and participates in the product requirements stage as a user advocate. We also have an important role as pre-sales enabler, meaning that we create pre-sales oriented content that can then be integrated into the product documentation itself. Our team produces documentation assets that support all stages of the product life cycle.

What are the challenges of having a team as this one?

• Where should technical writers fit within an organization? Engineering, product management, UX, support, marketing…
• Should technical writers specialize in a single area of the product or rotate amongst the different areas?
• How do you manage and foster different skills within the team?
• How do you keep the overall consistency of your product’s documentation? How do you make sure everything feels like a single package, preventing your users from noticing that different people created the documentation?
• How does the team and the company break away from the “documentation is just writing” mindset?

All these topics deserve a deeper reflection, so let’s save them for other posts. Stay tuned!