How technical writers can make themselves heard

Sunday, 28 November 2010 02:39

We technical writers are such shy and retiring types! It seems to be part of our make-up. We like to get in the zone, write perfect and beautiful documents, and expect others to see the value of our work. After all, doesn’t the perfection of a well-crafted document leap out at you? Don’t people know we’re the cool dudes who write the docs that rock?

Alas, sometimes we tend to fade into the woodwork and so does the documentation. Good documentation is one of those things that people don’t notice until it’s not there.

After hearing these and similar sentiments from technical writers at conferences and online a few times recently, I’ve been cogitating on questions like these:

How can we ensure that people know what technical writers do and appreciate its value? Even more, how can we foster in other people a sense of pride in, ownership of and responsibility for the documentation?

I’ve come up with a few ideas. I’d love to hear if you think they’re useful and if you have any to add.

Ideas for the short term

These are things we can start doing straight away. The crux of it is this: Technology is a great equaliser. Even CEOs read blogs, intranets, wikis and Twitter.

Blog. Everywhere. Write on our organisation’s intranet, on the company’s external blog and on our own personal blogs. Make our posts relevant to the technology and services our organisations sell and use.
Find out what social tools our top-level managers are using. Do they use delicious social bookmarking or mailing lists to share information? Hop in and contribute links to articles or blog posts that are relevant to what’s happening inside and outside the company. Let them know we’re on top of what’s happening.
Jump in to Twitter. Follow people and hash tags that are relevant to our organisation’s business. Start tweeting with those hash tags when we’re confident of our contributions.
Think of innovative ways to use Twitter in and around the documentation itself. Anne Gentle’s book, Conversation and Community, has some great ideas. I’ve written a few posts too about using Twitter in technical documentation. Twitter is a great way to reach our readers where they are and draw them into the documentation. We can point this out to other people in our organisation.
Suggest other ways to engage readers in the documentation, and explain how this is beneficial to our organisation as well as the customers. Also, from our own point of view as technical writers, we should bear in mind that we have internal customers as well as external. I’ve written a presentation about engaging readers in the documentation. Ellis Pratt has excellent material on documentation as an emotional experience.
Add a section to the company induction course, introducing new employees to the documentation and the technical writing team.
Does the company we work for hold conferences, user group meetings or other sessions where customers get together with people from the company? If so, encourage management to send a technical writer to the company’s next conference or user group meeting. Everyone will be amazed at the positive response from the customers.
Promote other ways in which we as technical writers can have direct contact with our readers/customers.
Agile? Attend the development team’s standups and retrospectives. Integrate the documentation development tasks into the iteration planning. Get people thinking of the documentation as an integral part of the product.
Let people know we care. Don’t be afraid to show a bit of emotion, especially positive emotion, about our role, our product (the documentation) and its contribution to the company.
Let people know that the customers care about the documentation too. If we receive feedback from the customers about the quality of the documentation, good or bad, publish it internally so that everyone in the company can see it.
Approach an influential person in the organisation, someone who already shows an interest in and appreciation of the documentation, and ask them to be our champion. Gordon McLean wrote about this idea over on ?one ma?n writes?, and someone where I work suggested it just last week too.
Consider broadening our role, or even simply changing our title to indicate that we already do more than just writing. It’s the old “technical writer” versus “technical communicator” debate. Too often, technical writing teams find themselves stuck in a vicious circle. Due to growing workload, we find that we have to decline involvement in broader communication matters and confine our focus to the documentation only. The result is that the rest of the company increasingly sees us as the folks who sit in the corner and write the docs. The company is less likely to grant our request for more technical writers. And our invisible workload keeps increasing. Instead, should we advertise ourselves as skilled in technical communication tools, techniques and analysis, and use this also as a reason for strengthening our team numbers and broadening other people’s view of the scope or our work?

A special idea for the medium term – a doc sprint

Hold a doc sprint. Only one of the aims of a doc sprint is to write the docs. A major benefit is that a doc sprint gets people working together with the technical writers on the documentation.

Invite everyone from within the company: developers, support engineers, product marketing, business analysts, CEOs and anyone else who has an interest in the documentation. Guess what – that’s everyone! As technical writers, we know that. But does everyone else?
If it’s feasible, invite people from outside the company too.
See my posts about planning a doc sprint, the results and more.

Ideas for the longer term

These ideas need a lot of consultation with other people in the organisation, so they will take longer to get off the ground.

Help our company set up and manage the company intranet. Pioneer the use of a wiki or other social tool as the intranet platform. Our analytical, technical and communication skills put us in a great position to do this. A successful implementation is a nice feather in our cap. What’s more, once the shiny new intranet is in place we can help other people use it and we can take advantage of it to spread our own news and views. I gave a presentation at TCANZ 2010 about using a wiki for an intranet. Alan Porter‘s new book, WIKI: Grow Your Own for Fun and Profit, is an excellent source of ideas on how to present such a project to management and how to make it succeed. See Tom Johnson’s review of the book.
Pioneer the use of a wiki or other social tool as a platform for our technical documentation. Anne Gentle’s book, Conversation and Community, has some great ideas here too. I’ve also written a few posts and presentations on this topic. For starters, try the article attached to this post about technical documentation on a wiki. Been there, done that? Now take it a step further by using the full power of social media in the documentation. There’s a shorter version available as a 20-minute video, Felt the earth move when I read your docs. (It’s the first 20 minutes of the video titled “Delivering World Class Documentation and Support”.)