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

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

Want a commercial Confluence wiki licence for just $5?

You got it! I work at Atlassian, and this week we’re selling fully-featured commercial licences for Confluence wiki for just $5. This is exciting news for contractors and small teams where up to 5 people will use the wiki. That’s why I’m blogging about it on my technical writing blog. Plus, the money goes to Room to Read

Here’s what it’s all about.

• The licence costs $5 now and is renewable for $5 too.
• Your wiki can have up to 5 users.
• Anyone can have one, provided you buy it this week. The offer ends on Friday 24 April. Update at 11am on Tuesday: The time zone applicable to dates quoted on the Atlassian web site is US Pacific Daylight Time. There is a limit to the number of licences available, so get in soon. Update at 8am on Thursday: We’ve passed the limit that was set initially, but have decided to carry on selling until Friday. Yaayy!
  
• It’s a fully-functional version of Confluence 2.10.3. (The support team won’t be able to answer questions about LDAP or performance tuning, but you’re not likely to need those when you have only 5 users. Also, you can run Confluence only as a standalone installation, not using a WAR installation inside another server.)
• It’s a commercial licence, so you can use it for business or personal use and it’s fully supported apart from the things mentioned above.

The details are on the Atlassian web site and in the FAQ. Licences are already flying out the door. Update at 11am on Tuesday: There is a limit to the number of licences available, so get in soon. Update at 8am on Thursday: We’ve passed the limit that was set initially, but have decided to carry on selling until Friday. Yaayy!

What if you don’t have your own server and you want to know where you can run your wiki? Adrian Hempel has written up some instructions on setting it up in Amazon’s Elastic Compute Cloud (EC2).

Mike Cannon-Brookes has been answering tweets in his inimitable style:

Want a commercial Confluence wiki licence for just $5?

And:

Want a commercial Confluence wiki licence for just $5?

BTW, for those who’ve got issues the same offer applies to our JIRA bug tracker.

As a self-professed wiki hugger, I think this is a great opportunity for technical writers and other people in small teams to get their own Confluence enterprise wiki.

Best of all, the proceeds of this week’s sales all go to Room to Read, one of the organisations supported by the Atlassian Foundation. They build libraries in the less developed countries of the world and publish books in the local languages. One of those countries is South Africa, where I grew up. There’s a graph on the Atlassian web page showing how far we’ve got towards our goal of raising $25,000 for Room to Read.

If you get a licence, let me know what you think of the wiki!

All on one page

When designing a piece of documentation, should we aim for one long page or many shorter pages?

Heh heh, I know, this is akin to asking whether a long piece of string is better than a short one. In the case of documentation, the answer depends very much on the subject matter, the output medium and the audience. So let’s aim for that amorphous but well known category “online documentation”.

Setting the scene

Until a couple of years ago, I was totally convinced of the value of short pages. I designed multi-layered documents, branching down into nicely categorised, easily digestible chunks of information.

“Don’t scare off your reader by cramming too much information into one page.”

Then I started working on a wiki, where readers have an easy way of communicating their opinion of the documentation we write. To my surprise, I found a number of comments from readers expressing frustration that they had to keep drilling down to get to the information they needed.

The most common request was to have the information “all on one page“. This was especially true of our installation guides. Many people hate having links all over the page, because they don’t know whether or not they need to click a particular link, since they can’t see what it’s going to tell them. Even if the writer introduces the link with “Read xxx to find out more about yyyy”, that is still not the same as being able to run your eye over the content and read or ignore it at will.

From talking to developers at the company where I work, I’ve discovered that most of them prefer having the information “all on one page” too.

Another relevant point is that we often don’t know what platform our readers are using. This is especially true when the documentation is online. Not so long ago, we could optimise our pages for 800×600 and be sure that we’d be serving most readers well. Soon 1024×768 was all the rage. But now, people are reading the same pages on their mega screens at work, then later on their laptop screens at home, and occasionally on their iPhones or other mobile devices while sitting on the bus or hanging from a cable car.

Other people are not using a screen at all, but a braille reader or a text-to-voice translator.

Simple HTML and web browser rendering are ideal for this situation. They allow the text to flow into the space provided by our readers’ devices. In fact, you could say that we would be doing our readers a disservice if we tried to force the content into one particular page format or length.

Having everything on one page improves your search results too. People will receive fewer matches to their search requests and will find the information more easily (provided they can search the content of the page once it’s loaded).

What happens if your page has a lot of pictures or other things that make it load slowly? Would this be a good reason for breaking the information up into smaller chunks? Probably not, these days. Many of our readers are on super fast connections. And most web browsers do a good job of loading the text first, so that you can read the whole page while waiting for the pictures.

How I’m writing now

My pages are tending to be longer than they were two years ago. They hold more information.

At the top of the page it’s useful to have a mini table of contents, in the form of a hyperlinked list of the headings on the page.

Within the page, I use headings and other forms of highlighting that help people to skim over the content and alight on the paragraph they need.

Here’s a link to an example page. The page tells developers how to create an XML file describing a plugin. The page contains a short introduction, an example of the XML file, and a description of each element in the XML file. We could split this page into three separate pages, one for each section just described. We could even split it into separate pages for each XML element.

Conversely, we could merge that page and all its sibling pages into the parent page (“Plugin Framework Development Hub”) and have one humongous long developer document.

“You wanted it all on one page? Try this for size!”

Nah, that’s going too far. The design job of splitting the information into logical chunks is still very important. But those chunks are a bit bigger than they were before.

If you’re working in an environment that uses single sourcing and content re-use, so much the better. Then you still have the fun of creating those nice neat bits, and you can just spew out the long page when the content is destined for an online environment.

How are you doing it these days?

OK, now it’s your turn. Shoot me down

But before you do, here’s a tantaliser for those who think chocolate and technical writing go hand in hand.

All on one page

One big piece of chocolate or many small pieces?

All on one page

At least here the choice here is easy: All of it

Book review – Managing Writers by Richard L Hamilton

I’ve just finished reading Richard L. Hamilton’s new book entitled “Managing Writers, A Real World Guide to Managing Technical Documentation”. It’s a good read, with useful information for managers, writers and technical communicators alike.

Book review - Managing Writers by Richard L Hamilton

I enjoyed the book, so I thought it might be a good idea to write up some of my thoughts and see if anyone wants to discuss them and the book. So here goes.

The book is an interesting mix of management techniques on the one hand (such as how to write a business case, or how to motivate people) and technical writing domain knowledge on the other hand (XML technology, content re-use, etc).

Even if, like me, you’re one of the many technical writers who want to stay technical writers and not move into management, I think you’ll find a lot of good information in Richard’s book. Most of us manage our own projects to a large extent. Also, it’s good to have an insight into what our managers are up to

Things I especially enjoyed in the book

The early section on the “elements of technical writing” is an excellent introduction to the complex and fascinating world of technical documentation. If your managers have never been technical writers themselves, get them to read these nine pages. With any luck, they’ll become so involved that they’ll read further.

One of my favourite bits is where Richard introduces the “black art” of scheduling:

“Schedules are the closest thing to a ‘black art’ that you are likely to deal with as a documentation manager. The good news is that as a documentation manager, you will rarely set schedules; the bad news is that you will rarely set schedules.” (Page 14.)

Why the bad news? Because someone else sets your schedule for you. Ah yes, that rings a bell

Richard has some excellent insights into and tips for handling performance reviews. This is a topic close to my heart, because I think we have not yet found a good way of doing performance assessments, bonuses and objectives. Personally, I don’t think that the “top 5″ mechanism works and I feel strongly that, if you need to use top 5s, they should not form part of an individual’s performance assessment. I think setting top 5s does not fit well with agile methodology unless you’re willing to adjust the top 5 goals at the drop of a hat. That makes them fairly arbitrary, and not a good marker for measuring a team member’s performance over an extended period of time.

For me, the rankings and ratings used in performance assessments are demotivating, demoralising and usually unfair. It’s weird and depressing to be judged as “meeting expectations” or “exceeding expectations”, let alone anything less than that. Some companies even declare an arbitrary percentage allowed for the “exceeding expectations” category e.g. only 10% of staff can gain this accolade. Huh? In the company where I work at the moment, everyone is a high achiever and everyone works hard. Management science needs to take this into account in some way.

On the subject of bonuses, I think all staff members should receive the same amount when the company does well. Not the same percentage of salary, but the same amount of actual money. (The only exception would be perhaps a ratio for part-time workers.) I understand that market forces decree that certain job descriptions get a higher salary. But I feel that bonus schemes should recognise that every part of a company is equally important in getting the company where it is.

To sum it up: I think our management gurus could work on finding a better way of doing all the things mentioned above. I can see that we haven’t found a good alternative yet. But we should! What do you think?

Getting back to Richard’s book he has some excellent things to say about focusing on and capitalising on a person’s strengths in a performance assessment (page 77). He also makes some great points about the problems with rankings and ratings (page 87).

The book also offers a concise summary of the agile environment and its potential impacts upon documentation (page 97). There’s advice on how to look like a profit centre rather than a cost centre (page 173) based on the fact that documentation is (part of) the product. This too is something all technical writers feel strongly about.

On the technical side, there’s a good summary of the differences between DocBook and DITA XML and how to assess which of the two would suit your project (page 189).

There’s a lot more in the book too. If you’ve already read it or if you read it after ploughing through this blog post, let me know what you think of it!

Details of the book and how I found it

The book is called Managing Writers, A Real World Guide to Managing Technical Documentation, written by Richard L. Hamilton and published by XML Press. Richard has a blog about the book and related matters.

Thank you to Anne Gentle for blogging about the book. That’s how I first heard about it. So I bought it from Amazon.com, to try it out for myself.

Now I’m going to pass it around the office. Andrew, one of the Atlassian technical writers, has already announced he’s first in line

Australian Cultural Evening at WritersUA 2009

The Australian Cultural Evening (ACE) is a not-to-be-missed event at the annual WritersUA conference. I was privileged to attend the ACE during WritersUA 2009. Tony usually writes about each event in hilarious detail (here’s his report from last year) so I’ll restrain myself to a few words and some photographs.

The ACE is restricted to Australians, erstwhile Australians, would-be Australians, anyone who has any Australian connection and people who have no connection whatsoever. This year there was an added restriction: “No kiwis!”

Another term for the ACE might be “pub crawl”, interspersed with a few mandatory “Aussie Aussie Aussie Oy Oy Oy” chants. It’s fun. Do it!

We started off at the Westin Hotel. Note the “Aussie Aussie Aussie” t-shirt:

Australian Cultural Evening at WritersUA 2009

Me see no evil:

Australian Cultural Evening at WritersUA 2009

Our next stop was the Blarney Stone Pub:

Australian Cultural Evening at WritersUA 2009

Birthday boy:

Australian Cultural Evening at WritersUA 2009

The flag, aptly poised next to the draught beers ad:

Australian Cultural Evening at WritersUA 2009

Here I am (Matt D, this one’s for you ) with two ACE gents:

Australian Cultural Evening at WritersUA 2009

I left at this point. I was exhausted. My presentation had happened that day, the Westin had creaked and groaned in the wind all the previous night, and I’d slept very little. Returning from the Blarney Stone, I counted myself lucky to find my hotel room again, after getting mislaid in the South Tower while my room is in the North Tower.

I believe the party went on I’m looking forward to reading other people’s accounts. Thanks to everyone for a great evening!