Communication channels for technical writers

Yesterday at work we heard that a team shuffle is happening. We have a new team, a couple of new team leaders and managers and a new focus. This affects just about every product and framework that I document. So next week I’ll be setting up new communication channels with the team leaders and managers involved. This made me think about how important our lines of communication are to us as technical writers. So this post is about the channels we use at work, and an invitation to you to let me know how you do it.

I think the top three factors that affect the quality of our documentation are:

  • The quality of the communication between the technical writers and the development and product management teams.
  • The quality of the technical writers.
  • The quality of the product being documented.

Another factor is the documentation tool. But I think if you’ve got the above three things right, then you can produce good documentation with any of the tools available to technical writers today. Why have I included the quality of the product as a factor? It’s hard to create neat documentation for a messy product. Technical writers can give input into creating a better product. That’s another blog post!

Communication channels for technical writers

Communication channels for technical writers

For me, the absolute top factor is the quality of the communication. Without a good flow of information, you’re just the guy who sits in a corner and does documentation.

When I start working with a new team or start a new job, I’ve always found that one of the very first things I need to do is to set up the communication channels.

The goal is to keep me in the loop but not overload me with meetings and information I don’t need. Equally important, I want to let people know who I am and that I’m here, interested, enthusiastic and just basically kicking!

The actual communication methods available depend on the company you’re at and the development methodology used. At Atlassian, we follow an agile process using all these methods and more:

  • Daily standups (short meetings, held standing up, where everyone says what they did yesterday and what they plan to do today)
  • The wiki (Confluence, of course!)
  • A feature, bug and task tracker (JIRA, equally duh)
  • IM and Twitter (but this is ad hoc and not something I need to plan for)
  • Email distribution lists (for informal communication within a team)
  • Planning meetings (where we plan the tasks for the next week or so)
  • Documentation-specific meetings (between the technical writer and the main contact person for each product)

So on Monday I’ll be setting up a quick meeting with the new team leaders and managers to suss out the names, times and places that matter. Maybe I’ll suggest we do it over a hot chocolate. Ah yes, the quality of the chocolate is that missing fourth factor 🙂

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 25 April 2009, in atlassian, technical writing and tagged , , , , . Bookmark the permalink. 8 Comments.

  1. Would adding forums to your wiki help? For example: – sticky topics, indication of hot / unread topics, all usual wiki functionality (topics = wiki pages) — drop me an email 😉

    • Hallo Guy
      I see the wiki forums are part of the Community Bubbles plugin. Heh heh, that’s such a cute name, and a very appealing feature set 🙂 It’s pretty cool that the plugin is free for people who have the $5 Confluence starter licence. I haven’t tried Community Bubbles myself, but I reckon the working example looks like a very useful communication tool. Thanks for pointing it out to me!
      Cheers, Sarah

  2. Quebec Educational Mathematics and
    Science Alignment Project
    Dawson College
    3040 Sherbrooke Street, Ouest, Room 6B.17-1.
    Westmount, QC, H3Z 1A4

    April 28, 2009

    Dear ffeathers,

    We would like to request permission to incorporate the second photo from the website
    on Cement
    in the teaching materials we are preparing for Quebec High Schools. As part of the reform curriculum (QEP), students will work on open-ended tasks, called Learning and Evaluation Situations (LES) over several weeks.

    These LES were developed, during the past year, by teams of high school and college teachers with the help of the Quebec Educational Mathematics and Science Alignment Project (QEMSAP). QEMSAP’s long term goal is to develop a comprehensive plan for the active involvement of science educators in the Quebec educational system.

    Of course, we would cite your website, in the LES.

    These teaching materials, will be distributed to the Anglophone high school teachers to be used in the 2009-2010 academic year.
    It is hoped that, in the interest of the students, you will grant us permission for the above. Your reply by May 1, 2009 will be greatly appreciated.

    We can be contacted for further information, at 514-931-8731 (ext. 1692) or by email:,

    Silvia d’Apollonia
    QEMSAP Coordinator
    Marilou Alforque

  3. Hallo Silvia

    Thank you, I am honoured that you’d like to include photographs from my blog into the QEMSAP educational material. Please feel free to include any image or other material from my blog into your teaching materials, with a link to my blog as the source of the material.

    I’ll reply to you personally via email too.

    Cheers, Sarah

  4. I’d like to know what prompts such shuffles. Internal politics or genuine need?

    • Hallo Craig

      In our case, there is an excellent reason for the team shuffle. We’ve realised we need an additional focus, on making our products work together as well as on developing the individual applications themselves. We’ve been working towards this for a while, and now we have a new team and new product manager to add impetus to the work. I’m quite excited, because this will make the documentation easier. It will also increase the development velocity of the integration tools and other integration-related stuff. So there’ll be more documentation for me to do. Of course, that could be seen as good or bad 😉 but it’s work I really enjoy.

      It’s a good question you raise. In the past, I’ve worked at organisations that indulge in the occasional shuffle just to keep the troops interested. Or that’s how it’s seemed to the troops themselves. So I guess it all comes down to communication again.


  5. Did you end up trying the Community Bubbles plug-in? How did it go?

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 )

Google photo

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