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.

Converting documents between a wiki and Word, XML, FrameMaker or other help formats

This week I published a post on the Atlassian blog about single source publishing on a wiki. I’m cross-posting it here because it may be useful to technical writers who read this blog.

The post discusses a few of the reasons why we may want to write our documents on a wiki and then publish them to other formats, or conversely write the documents using another tool and then publish them to a wiki as one of the delivery formats.

Next, the post recommends some good tools for converting content from these formats into Confluence wiki format:

• From Microsoft Word to Confluence wiki
• From Adobe FrameMaker to Confluence wiki
• From DITA XML to Confluence wiki

And some tools for converting content from a Confluence wiki into these formats:

• From Confluence to PDF
• From Confluence to Microsoft Word
• From Confluence to HTML
• From Confluence to XML (Confluence-specific format)
• From Confluence to DocBook XML
• From Confluence to Eclipse Help
• From Confluence to JavaHelp

In case it’s useful, there’s also a post I wrote a while ago about getting content into and out of wikis. That post looks at a couple of other wikis as well as Confluence, and covers a wider range of tools. The new post on the Atlassian blog is more up to date and is specifically about conversion tools to and from Confluence.

If you’re interested, mosey on over to the Atlassian blog and take a look. I’d love to hear your experiences with the tools mentioned in the blog post, or if you’ve used any other tools or need any other conversions. What did I miss out? There’s an interesting discussion going on already. Here’s the link again: Technical writing in a wiki – single source publishing.

Technical writers of the world unite – #twotwu

“If technical communicators ruled the world, I would take on…” A few weeks ago, I was given that sentence fragment and told to speak on the topic for five minutes. My audience was the group of technical communicators at TCANZ 2010.

What would you have said?

As far as I remember, I started by saying I would take on everyone in the world who does not know what technical communicators do. This rose from my heartfelt dismay when people ask, “What do you actually do all day?”

I then wittered on about the opportunities that modern technology offers us to do just that. Blogging, Twitter, wikis, the technology that makes it possible to hold doc sprints… You know what I mean.

More recently at ASTC (NSW) 2010, Neil James proposed the idea that we may move towards a single, unified communication profession.

And now, in a sublime conjunction of those two trains of thought, TWOTWU is born.

This post is just for fun. It’s not a serious attempt to rule the world or to unite all technical communicators! I want to see what cool ideas and discussions this post may generate, bearing in mind that sometimes the most creative ideas arise from animated, casual discussion amongst friends with a common passion.

If you’d like to join in, add a comment to this post, or tweet on Twitter with tag #twotwu. I’ll collect the tweets and add them as comments to this post every now and then. If you like, you can subscribe to the comments on this post.

To wit, twotwu

Ryan Maddox drew the owl, especially for this post. Thank you Ryan!

Every doc sprint is different

We’ve just held our second doc sprint. It was very different from our first, but just as awesome. For me, the best thing about both sprints was the people. Getting to know people and working with them in the intense focus of a sprint is great. Hearing and seeing their ideas for our documentation is simply inspiring.

We ran the doc sprint concurrently in Sydney and San Francisco on Thursday 4th and Friday 5th November. There were also a number of people working remotely, as far flung as Israel and Moscow. As you can imagine, the word “concurrently” is a bit fuzzy, with all those time zones involved!

We had different aims for this sprint: In the February sprint we worked on developer documentation, whereas this time our target was user-focused quick start guides. The sprinters were different too…

The people

For the previous sprint, we invited developers from inside Atlassian and from our plugin development community. This time we had developers, technical writers, support engineers, business analysts and all sorts. They were Atlassians, partners, community developers and also people who use our products and were generous and interested enough to take part in the doc sprint. Here’s the list of attendees. We’ll be putting up the photos in our Hall of Fame soon!

The photos are also on Flickr. Search for the tag #AtlassianDocSprint or look at these sets:

• Matt Hodges’s Flickr set.
• My Flickr set.

The results – “awesome” is the only word for them

We wrote 25 guides consisting of around 42 pages, some complete and some needing more work before we can publish them. A few people started creating videos to supplement their guides too.

In addition Jim Intriglia worked on his guides to using JIRA on Linux, which he will publish on his blog soon. Jim also wrote a very nice post about the doc sprint.

I’m amazed at the energy and skill that people put into their guides. People also let us know that they enjoyed the sprint hugely. We put a lot of work into the planning, and especially into creating the wish list of guides to write. This really paid off. Congratulations to Giles, who organised this sprint!

Chocolate, haiku and fun

Although every sprint is different, some things never change. Inevitably there was chocolate.

To the great delight of all.

Joe’s Tim Tams went missing very early on in the proceedings. All that was left was a lonely half a Tim Tam perched on top of Joe’s Dell. I dubbed it “Eric the half a Tim Tam“.

Everyone knows that chocolate and haiku are a match made in heaven. But… just how many syllables are there in the word “chocolate”? Add the sublime technology of IRC, and this is what you get:

Take a look at the doc sprint haiku competition. This was the winning entry, by Daniel Green in Israel:

No time to eat now.
Should be writing more content.
Too late, never mind.

Retrospective and what I learned from this doc sprint

At the end of the sprint, we held a half-hour retrospective session (one in Sydney, one in San Francisco) where people could tell us what they think went well and what we could do better next time. Here’s the doc sprint retrospective page on the wiki.

Having the wiki as a tool for the retrospective, as well as for writing the documentation itself, was very useful. Remote sprinters just added their feedback by editing the retrospective page itself, if they could not attend the session in person or online. Some people were working in weird time zones.

We’ll be summing up and voting on the results over the next week or so.

From my own point of view, I learned a lot from this sprint, as I did from the previous one too. For me, the main learning points this time were these:

• A number of sprinters said how valuable it had been when they were able to collaborate with a technical writer, to “get the words right”. It was very heartening to hear how people appreciate our skills. We had consistent feedback that people wanted to “pair” with us more.
• Leading on from the above point, it may be a good idea if the technical writers don’t have specific documents to write during the next doc sprint. Instead, they could spend their time pairing with each of the other sprinters in turn. This is especially valuable if the other sprinters are not technical writers.
• We had made a specific decision for this sprint, not to create templates or detailed guidelines. We wanted to leave people free to design their guides in any way they chose. Judging from the feedback we received, that may not have been the best decision. Instead, next time we will consider light-weight templates and style guides as we did for the first sprint.
• This doc sprint was only two days long, so there was only one webinar in which the two main time zones coincided (Sydney and San Francisco). That was a pity. It would have been nice to have more contact with the San Francisco sprinters, and with everyone else working remotely. Our previous doc sprint was three days, and that seems to be a good period.
• The final day of this sprint was a Friday. That meant that the San Francisco people were finishing the sprint on Friday afternoon, which was already Saturday morning here in Sydney. Very few Sydney-siders were watching. Instead, perhaps we should aim for Monday to Wednesday for our sprints.

Let’s leave the retrospective with a look at this feedback point:

VERY concerned about the theft of chocolate during the sprint Should encourage people to lick their chocs when they get them.

We can all guess where that one came from!

A man and his chocolate are not long parted

Joe was reunited with his Tim Tams. I’m not sure what happened to Eric, but I’m guessing it’s a tragic yet heartwarming tale complete with much philosophy and soul-searching. To bee or not to bee, half a Tim Tam philosophically, ipso facto may just bee a conundrum too profound for this doc sprint. Perhaps we’ll solve it in the next.

Of technology and trees

Some sprinters were surround by technology. Here we are in Sydney, hooked up to San Francisco via a video conference (television on the left) and to remote sprinters via a webinar (screen at the back).

Some sprinters were surrounded by beauty.

Thank you Jim for giving me the opportunity to add a tree or two to this post.

ASTC (NSW) 2010 wrapup

This weekend I attended the ASTC (NSW) 2010 conference in Sydney. That’s the annual conference of the Australian Society for Technical Communication (New South Wales branch). I had a good time, learned a lot and met some great people.

That’s what it’s all about, isn’t it: the people. I made many new acquaintances and met up again with old friends. The conference lasted two days, Friday and Saturday. There were about 50 conference attendees, so that’s plenty of scope for networking and making contacts!

The sessions

There were 14 sessions over the two days of the conference. Topics ranged from interior decorating through to travel insurance, with some technical writing along the way. I attended all the sessions and took notes from some of them so that I could blog about them. I wish I could have blogged about them all, but I just don’t have the time. Every single speaker was great and every session enjoyable.

These are the sessions I have blogged about, with a link to each post:

• One profession, many practices – towards a unified communication profession, by Neil James.
• Nobody ever came to work intending to do a bad job: Righting the wrongs of corporate information, by Bede Sunter.
• Five ways to deliver an intranet that works for staff, by James Robertson.
• Software usability: some second thoughts, by Jon Jermey.
• Counting on you: communicating numbers, by Irene Wong.
• Travel insurance: the communication challenge, by Rob McGregor.
• How to write for translation: New challenges for the writer, by Sarah Forget.
• Six step system to winning documentation using graphics: Interior decorating and the art of documentation, by David Keen.

More sessions:

• I spoke about using social media and other techniques to engage your readers in the documentation. If you like, you can download a copy of my slides in PDF form (2,593 KB): Engaging your readers in the documentation (slides only). I’ve put a lot of information and references into the speaker’s notes too. Download the slides with notes in PDF form (2,578 KB): Engaging your readers in the documentation (slides with notes).
• Rachael McAlpine presented two sessions. The first was titled From copywriting to content strategy: the silver lining to your career cloud. The second, Year after year of usable, accessible, findable content, focused on comparing the benefits of the online training solutions offered by her company, Contented, against the costs of face-to-face training.
• Bob Trussler spoke about Clumsy styles: our opportunity for excellence. He gave us some excellent tips on how we can use our Word document skills, especially with Word styles, to improve the documents produced by our organisations.
• Charles Cave gave a great case study on Creating e-learning using PowerPoint and Articulate, showing us how he uses a combination of PowerPoint, Articulate and Captivate to create and host e-learning material. He also gave us this great tip: use screenr.com to create, tweet and download screencasts as MP4, free of charge.
• Elizabeth Abbott gave a very useful presentation on the project management skills that are essential for any technical writer, whether we’re working as independent consultants or as an employee.

The people and the fun

A special thank you to Janet Taylor, for inviting me to speak at the conference and for getting me involved in the first place. It was an excellent event, heartily recommended for all technical writers and communicators. A big thank you also to Bede Sunter, Rob Phillips, Jasmine Andrews, all the ASTC committee and everyone else who put so much hard work into organising this event.

ASTC (NSW) 2010 wrapup

(Click the photograph to see a bigger version.)

More photos on Flickr

Take a look at my photo set on Flickr. You can view it as a slide show too. Let me know if you have any more photos or if you find any other blog posts or news about this conference. Hope to see you there next year!