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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 January 2011, in atlassian, Confluence, technical writing, trees, wiki and tagged , , , , , , , , , , , , , , , , . Bookmark the permalink. 12 Comments.

  1. Hi Sarah,
    Thanks for summing-up the main ideas of good user documentation.

    It is an advance that the Doc sprint results became the basis of a part of Confluence core documentation.
    Keep going!

    Because the Doc Sprint is still a sprint, it may be not so much a source of complete documentation, as a event for generating new ideas, sharing expressions and inventing directions to improve existing docs, documented tools and documentation process.

    • Hallo Katya
      Spot on! I think you’re exactly right. From my point of view, the best things about a doc sprint are the people, the contacts and the sharing of ideas and enthusiasm.🙂

  2. Oooh… I’m interested in the following:

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

    This seems to suggest that your users are going to arrive at the first page of the content and read the through it in a linear order. Is this a use pattern that you have evidence for?

    -Michael

    • Hallo Michael

      That’s a good question. We’re basing the design of the docs on that assumption, for two reasons.

      Firstly, wikis are still seen as a fairly new type of platform (even though they’ve been around a decent time already). Many people are asking the question, how does a wiki do X, where X is something that people are already doing on another type of platform. In the case of technical communication, there’s a lot of material already out there telling us that wikis are good because they tap into the web world so well. What’s missing is the detailed documentation on exactly how we can make the wiki do what we need to do.

      The second reason we can make that assumption is that our website targets a small set of use cases. It already does that, and a soon-to-be-released update will be even more focused on a set of use cases. We can assume that a number of people will come to the documentation looking for the “how”, since the website draws them in by telling them the “why”.

      So, people will becoming to the docs looking for a step-by-step guide on how to use the wiki for a particular use case. And they’ll be likely to start at the top and read in sequence, until they figure they know enough to fly on their own.

      Of course, people will also land in the middle of the pages via Google searches. For that reason, every page tells people that it’s part of a multi-page guide, and gives them a link to the start of the guide.

      Cheers
      Sarah

      • Bravo Sarah!

        Sounds like a great approach. The best part is, you’ll be able to see if it’s working or not by the comments, etc people add as they interact with it.

        IMO: It sounds like you’re right on the money to me. But perhaps the best thing about it is that if it’s not meeting user/reader expectations, you’ll hear about it loud and clear through the comments.

        Keep us posted!

        -Michael

  3. Hi Sarah,

    I’ve been following your blog for a while. I am looking forward to reading your guide, it seems the stars have aligned correctly in regards timing of this guide for me as i am evaluating the wiki thing for our product documentation.

    I had looked at both you and Mindtouch, I spoke to my boss about doing some research into it and he gave me some (very limited) time to begin in March/April.

    So i thought to myself that if i want to get anywhere this project i will have to devote some of my own time to it and i was thinking to myself ‘if only there was a guide on how to do this, it would make my life so much easier and save me so much more time!’

    Well the Gods listened (at least for Confluence)! I hope to keep you informed on my progress and see where it leads to.

    Well done to you guys on this initial effor, its exactly what people like myself needed!

    Ally!

    • Hallo Ally

      I’m so glad the guide will help you out. Doing technical documentation on a wiki is a lot of fun and very rewarding.

      The guide will get your documentation space up and running, and help you with release management. Taking things a step further, I’ve written a blog post and presentation on how you can use the full power of the wiki to engage your readers and embed content from other social sites:
      https://ffeathers.wordpress.com/2010/06/13/aodc-2010-day-2-engaging-your-readers-in-the-documentation/

      Let me know what you think of it.🙂

      Also, the Atlassian technical sales engineers are really great at answering specific questions you may have while evaluating Confluence. You can download an evaluation copy from the website:
      http://www.atlassian.com/software/confluence/try.jsp

      The technical sales team will be in touch by email after you’ve downloaded the software. If you prefer, you can just send them an email at sales@atlassian.com

      Let me know how it all works out for you.

      Cheers
      Sarah

      • Hi Sarah,

        Thanks a lot for the above information and links. I am looking forward to using and testing your product, though for the time being it will have to be a weekend/after work project. I will contact the sales team, but before doing that i would like to jot down our requirements fully so that i have something to evaluate against.

        Thanks

  4. Hello Sarah,

    Thank you and your team who worked on the Sprint to put the Technical Writing documents together. It has been very helpful in getting started putting together documentation in the Wiki World. I’m sold on the (relatively) new concept for many businesses to translate all of their documentation into Wiki, but still run into hold-over issues from time to time. My current issue deals with Printing a Wiki page (from Confluence), and being unable to control the output as far as leaving huge gaps in content because, for instance, not all of one image fits on the current page so it gets “bumped” to the next page, leaving a gaping hole from whence it came.

    I’m looking to find that someone has written some sort of macro whereby one can “define” workspace within a Wiki markup on a “per page” basis. In other words, here is a defined space (let’s say 8.5 X 11 inches for here in the States), and everything within that space will be “reduced to fit” when one goes to print to PDF or likewise. I know that sounds like backwards thinking or reverting back to Word World, but for certain applications (marketing or sales usage) it would be very helpful. I’ve scoured blogs and helps all over, and as of yet, have been left wanting.

    Any ides?

    • Hallo Nate

      I haven’t seen anything that suits your requirement, though the problem of images causing huge gaps is a common one.

      An idea may be to take a look at Scroll Wiki Exporter, a Confluence plugin:
      https://plugins.atlassian.com/plugin/details/7019

      Also Scroll Office, which has a sophisticated export to Word:
      https://plugins.atlassian.com/plugin/details/24982

      Both of the above plugins offer good customisation and formatting options. You could take a look through their documentation, and their blogs on the Atlassian blog, to see if they offer something that will help. Otherwise, you could get in touch with the Scroll team. They are great guys and have a lot of expertise in Confluence to PDF and Confluence to Word conversions.

      Another idea might be to search the Confluence user forum:
      http://forums.atlassian.com/forum.jspa?forumID=96

      If no-one has asked the question before, you could post the question and see what answers the community comes up with.

      Let me know how it goes – I’d love to hear the answer.🙂

      Cheers
      Sarah

  1. Pingback: Things to show for 2010 « JodieM.com.au

  2. Pingback: Tweets that mention New guide to developing technical documentation on a wiki « ffeathers — a technical writer’s blog -- Topsy.com

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: