Blog Archives

New guide to developing technical documentation on a wiki

We’ve just published a new set of documents in our wiki’s user guide: Developing Technical Documentation on Confluence Wiki. We started writing the guide during our recent doc sprint. Since then, I’ve put it through a technical review and added some bits. Now it’s part of the “official” documentation. That’s a doc sprint win. 🙂

Designing and developing this suite of documents was a lot of fun and very interesting. The project serendipitously combined a number of aims, all rather different in nature:

  • Think up something to do in the doc sprint.
  • Involve other doc sprinters in the project, especially people from outside the company.
  • Spike a “use-case focused” guide and make sure the result is useful even though it’s a spike.
  • Tie together all the information we have in various spots, about writing technical documentation in a wiki.
  • Put the guide into the core Confluence documentation, so that it will be maintained and updated from now onwards.

People who worked on the guide during the doc sprint

A number of people collaborated on this guide. Two were Atlassians and the rest were people who joined the doc sprint in November:

…and others who reviewed the pages, working remotely in various spots around the world.

What is a “use-case focused” guide?

One of the things we’d like to do is to provide more “use-case focused” documentation. By that we mean that the guides should focus on a specific use of the product. A better term might be “domain-focused” documentation. For example, for Confluence we should write documentation about how to use Confluence as an intranet, how to use Confluence as a knowledge base, how to use Confluence for technical documentation, and so on.

This suite of documents is the first stab at such a user guide.

Design of the guide

These are the principles on which the guide is based. It’s just a spike, so we didn’t hit all these goals. But it’s a very good start.

Write topics that are task-focused on the macro level. The words “on the macro level” are very important in this context. It’s a well-known principle of technical documentation that guides should be task-focused, as opposed to feature-focused. We tell users how to do the things they need to do, rather than documenting the features of the product. At the moment, much of our documentation is nicely task-focused on the micro level: How to add a space, add a page, add a comment, set page restrictions, and so on. But it’s not task-focused on the macro level: How to set up a space for technical documentation; how to push a document through the draft/review/publish workflow (using page restrictions); and so on. One good way of addressing this problem is to produce use-case focused (or domain-focused) guides.

Tell people only what they need to know. Focus on the aspects of Confluence that the target users (technical writers, in this case) need. Ignore the other aspects. For example, on a typical technical documentation wiki it’s not important to know how to follow users or use the other “networking” features of the wiki.

Employ progressive elaboration. Progressively reduce the level of detail in the step-by-step instructions, while increasing the complexity of the concepts. Start with fairly detailed instructions for the basic functionality, in the first section of the guide. Become less detailed in later pages, because the users will have become more familiar with Confluence. At the same time, they will be dealing with more complex topics. But that’s OK, because they’re in their field of expertise (domain).

Encourage users to explore the product and learn from the UI, rather than telling them exactly how to do every single thing. If a user guide is very comprehensive, it gives the impression that it documents the entire product. If something isn’t in the docs, people will think it’s not in the product either. They won’t try to explore the product. We should encourage people to trust the UI. Also, if a user guide is very dense, people won’t find what they need in it.

Employ content re-use. Use Confluence’s {include} macro to pull in content from existing pages, so that we can avoid duplicating content and can thus reduce maintenance.

The result

I’m delighted with the resulting guide: Developing Technical Documentation on Confluence Wiki. It’s not perfect, but it’s a very usable and useful piece of documentation and it certainly fills a gap. Thank you again to all those who took part in developing this guide, and to everyone who took part in the doc sprint!

Sydney Red Gum tree

A magnificent Sydney Red Gum tree I encountered on my walk this morning. Shot taken from a rocky ledge half way up the height of the tree.

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

Every doc sprint is differentFor 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:

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.

Every doc sprint is different

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.

Every doc sprint is different

To the great delight of all.

Every doc sprint is different

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“.

Every doc sprint is different

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:

Every doc sprint is different

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.

Every doc sprint is different

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

Every doc sprint is different

Some sprinters were surrounded by beauty.

Every doc sprint is different

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

%d bloggers like this: