How technical writers can make themselves heard

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 man 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”.)

The punchline – we’re in a good position

In all things we do, we can use our technical writing skills to get our message across. Make it short, punchy, targeted and structured.

Perfectly beautiful

I spotted these mushrooms while I was out walking in the bush a while ago.

How technical writers can make themselves heard

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 28 November 2010, in technical writing, wiki and tagged , , , , , . Bookmark the permalink. 8 Comments.

  1. You’re right, you’re right, you’re right, but as an outsider coming in(to the profession), I can’t help thinking you’re wrong, wrong, wrong.

    Nobody notices the plumbing till it’s not there, and plumbers do some beautiful work (though you’d have to be another plumber to appreciate it). Still, I don’t notice plumbers having the same existential angst as technical communicators, who both (by all accounts) get handsomely rewarded for their efforts.

    I just can’t help thinking you’re on a losing battle here. How would you feel if the janitor started tweeting the docs team about the great new U-bend he’s just installed and would anyone like a guided tour just after lunch?

    • Ha ha, I love this comment! People on the bus turned to look at me when I burst out laughing, reading it. 🙂

      There’s a lot of truth in what you say, Phil. It’s the first time I’ve ever seen documentation compared to a U-bend! How’s about a nice curvy installation guide. Speaking as someone who currently has problems with the plumbing, I do appreciate a good U-bend.

      I’ll trade your analogy for another: the documentation, rather than being the plumbing, is the front door.

      * It’s often the first thing people see.
      * If it’s aesthetically pleasing and easy to get through, that’s good.
      * If it’s too ornate and detracts from the rest of the building, that’s bad.
      * Enthusiasts write about its perfect design and praise the designer and craftsman alike. 🙂


      • Actually the analogy was inspired by this

        But my wider point is that good documentation should be invisible. Going with your analogy, no one thanks the door-maker for successfully entering the building, and yet assuredly they couldn’t have done it otherwise.

        Similarly, good documentation should be invisible. When the user solves a problem/learns how a task through the docs, it should seem as if they did it themselves. The docs are a tool, after all. The door-maker doesn’t go to bed at night marvelling at the skills of the hammer-maker and the nail-manufacturer (and didn’t the sawmill do a great job planing those planks to perfection?).

        But maybe enough with the analogies! 🙂

  2. Nice post, Sarah.

    One thing that raises your profile in the company is to provide internal ‘documentation’ for helping the staff solve problems. For example, I’ve created several ‘how to’ videos/screencasts for my team that address the common issues they have with the corporate Word template. While I can troubleshoot this stuff with them over the phone (I work remotely, but only 3 days a week), having the videos available means they can get help at any time, whether I’m there or not. Each video addresses a single issue, and none is longer than 2 minutes. It’s a small thing, but it’s saved a lot of people a lot of time and frustration — and has raised my profile.

  3. Documents that are “perfect and beautiful” don’t count nearly as much as documents that are delivered ahead of schedule and under budget.

  4. I like the doc sprint idea. I also feel good old stuff such as writing correct information in manuals, asking technically relevant questions, contributing to product development, providing ideas for UI improvement, talking about users, and putting in bugs in the quality tool would work too 🙂

  1. Pingback: Tweets that mention How technical writers can make themselves heard « ffeathers — a technical writer’s blog --

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: