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:

• Jodie Miners
• Ekaterina Stepalina
• Eliane Pohl
• Matt Doar
• Doug Morrison
• Matt Hodges
• Sarah Maddox – that’s me, folks

…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!

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.