Values of effective tech writing teams at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. One of the sessions I attended is “7 Values of Effective Tech Writing Teams”, by Joao Fernandes. Here are my  notes. All credit goes to Joao, and any mistakes are my own.

Joao Fernandes started by saying that success and effectiveness are words without meaning, unless you have a specific goal in mind. So, what’s the goal of tech writing?

Some answers are:

  • Teach people how to use a product.
  • Explain complex information in a clear way.

But those goals aren’t ambitious enough, says Joao. There’s something more profound that guides us. Our users don’t want to read the docs. They want to use the product. So Joao proposes the following goal for tech writers:

Help build products that need no documentation.

Given that premise about our goal, these are my notes on the rules that Joao discussed:

Be the CEO of the docs. Define a vision for the docs, communicate that vision to all interested parties, and make sure others follow it. Make sure you schedule time to do strategic work, as finding that time will be difficult otherwise.

Know the market, product and users. Understand the need that your company is trying to fill in the market.

One of the main points of this session is that we need to decide what documentation is required (the answer may be, very little), and where best to put it (the answer may be that the doc is part of the product rather than traditional documentation). Joao suggested we should apply the 80/20 rule when deciding which docs are required.

Another point is that effective tech writers ask “why” all the time.

Effective tech writers use words as tools, in the same way as developers use programming tools. A natural language is an interesting tool, because it allows for the transfer of knowledge from one person to another. Sometimes the transfer doesn’t go too well. We can complement language with other tools, such as diagrams. And we can adapt the language to make it more effective.

Sharing knowledge is also an important part of an effective tech writer’s role. Coach others, and create resources to help new members of the team.

Thanks Joao for a beautifully presented session!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 25 May 2016, in technical writing, Write the Docs and tagged . Bookmark the permalink. 1 Comment.

  1. Great summary. Thanks for writing these up.

Leave a Reply

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

You are commenting using your 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: