What makes simple documentation

What makes simple documentation? Our technical writing team is asking itself this question at the moment. We’re also asking our product managers to give us examples of simple documentation, and counter examples of documents that could be made simpler. I interviewed my first PM on this topic this week: Dave O’Flynn, product manager for integration at Atlassian. His answer was so neat, concise and helpful that I decided to blog about it.

Firstly, I was impressed with the way Dave quickly and unobtrusively rephrased my question. I asked him:

How would you define simple documentation and do you have some examples of simple docs?

Dave’s reply was:

The Dragons documentation is the best of example of a complex problem explained simply.

Neat. A self-documenting reply!

Secondly, it’s cool that Dave chose the Dragon Slayer documentation as his example. Dave sat back, put his hands behind his head and gave a concise list of points about what makes those documents simple:

  • They are bite-sized.
  • The language is clear and simple.
  • They are consistent.
  • The reader starts at the top and reads down. There are no links that force the reader to branch off to other documents and then come back again.
  • Each page gives you a goal, then tells you at the end what you have succeeded in doing.

That’s a very useful list. One of our team members has already applied these points to a new set of documentation she is designing. I’m looking forward to more feedback from our product managers and team members. And I’m wondering, does anyone else have any ideas about what makes a simple document?

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 July 2011, in atlassian, technical writing and tagged , , , , , . Bookmark the permalink. 19 Comments.

  1. Great article Sarah. Thanks for sharing.

  2. Regarding the “Dragons” documentation, I think that’s part of what makes it so easy and simple is how it chunks information. Instead of having four or more different pages for installing Jira, it’s all kept together as a series of steps, with the anchors for quick navigation. At the same time, the stages of the process are separate pages so that you don’t end up with one long scrolling beast of a page. It’s a great example. 🙂

    • Hallo Arwen
      Thanks! Dividing the information into chunks — that’s a very good point. Deciding just how to split it up is quite a challenge sometimes. Some people prefer seeing everything on one page, even if it means they have to scroll for ever. Others like separate pages. The art is in deciding just what the “everything” means. Easy! 😉
      Cheers, Sarah

      • Deciding how to divide the information into chunks is what gets me. To achieve a smooth flow, things must be split. Decisions, decisions.

      • Haha. Good point. Deciding on that “everything” is everything.

  3. Great piece. I notice the Dragons docs have no problem using the word “you.” That lit up another forum quite furiously recently. Some are adamantly against using it, preferring to rewrite instead.

    • Hallo Craig
      Yes! That’s a very debatable choice. I like using “you”, because it is direct, simple, and makes it clear who has to perform the action. In most cases, it’s either the reader (“you”) or the application (“JIRA” or whatever). If “you” is banned, then we sometimes have to resort to the passive. An alternative is “we”, but that sounds odd. On the other hand, “you” can sound too abrupt and imperative, particularly in some cultures.
      Cheers, Sarah

  4. I think “simple” must be contextually defined. There’s simple to write, simple to maintain, and simple to read. Not all of these overlap. Perhaps even more important is “simple to understand”, meaning the user can get in and out of the docs quickly, soaking up what s/he needs to know to do his/her work…

    • Hallo Michael
      Great point. In the Dragons docs, the aim is to make the instructions simple to follow. That’s adding another one to your list! It made me realise that the “x” in “simple to x” depends on the type of documentation. Thanks for adding a different perspective to the conversation!
      Cheers, Sarah

      • Ha. Well, it comes from a former life where there were some severe collisions with engineers about a document that was written by engineering and simple (to maintain). Unfortunately, it was anything but simple to understand or follow. Now, I always to try to get to the bottom of what someone means by “simple”…as obvious often isn’t. 🙂


  5. I was building a Lego set with my son last weekend and the similarities between Lego instructions and documentation struck me. Small steps, plenty of them if necessary. Changes from one step to another are obvious, and if need be, called out with a separate “here’s what changed”. They keep the perspective of the reader constant for as long as possible, then make it obvious to turn the model over.


    • Hallo Matt
      I’m not au fait with Lego instructions, but I guess they are documentation too. Your comment made me think of documentation as Lego, too. Building blocks that you can plug together as needed… 😉
      Cheers, Sarah

  6. Sarah, thanks for a very interesting topic! I work with user interfaces, not documentation, but often together with tech. writers/communicators.
    Wanted to ask, do you test documentation at Atlassian? We test user interfaces on new users, because it’s pretty useless to test on the developers that created the application. But as long as I know the docs are rarely tested on new people. The guys who approve the doc’s draft are usually the ones who know all ins and outs of the program 🙂

    • Hallo Sasha

      That is a very good point! We do occasionally test the documentation, but it is not part of our regular procedures. The feeling is that it would take too much time to do user testing on every new document. One set of documentation, the Dragon Slayer documentation, is tested each time we do a major update. The feedback from the testing is always very useful indeed.

      As you mentioned, the subject matter experts are not always the best people to test documentation. It would be excellent if we could organise user testing for more of the new topics. The art is in deciding which to test, and in measuring the time required against the benefit gained.

      Thanks for an excellent point! Testing would be a very good way of working towards simpler docs.

      Cheers, Sarah

  7. In order to create simple documentation, we should take into consideration the following characteristics: easy to use, easy to understand and easy to find.
    First of all we should focus our documents on tasks. Someone said “Show me how the system works not his functionality”. Focusing on real tasks not on product functions helps users with their “daily tasks”. This way users won’t avoid anymore reading documentation before using a product. It is highly important to provide clear step-by-step procedures: make each step a clear action for users to take, group steps for usability, clearly identify optional steps, and identify criteria at the beginning of conditional steps.
    In order to create easy to understand documentation, we should focus on the meaning, avoid ambiguity, present similar information in the same way and much more.
    The last but not the least important characteristic to create simple documentation, easy to find, depends on organizing information, retrievability, and visual effectiveness.
    Putting it all together is not that simple. Writing successful simple documentation comes with experience.

    • Hallo go3eaana

      I think you’re absolutely right. You’re looking at it from the point of view of the reader/user: what is simple for them. And that is documentation that (a) gives them just what they need to know, and (b) leads them through the steps they need to follow, if they get lost.

      Sometimes it’s tempting to look at a documentation suite at a high level, and say it doesn’t look simple because there’s too much detail. If you remove the detail, though, some users will suffer.

      It’s quite a conundrum. I think we need a two-layer approach: An entry path that looks simple, and lots of detail under the covers.

      Cheers, Sarah

  1. Pingback: Today’s Reading List – Magically Appearing Phone Edition

  2. Pingback: Example of simple documentation « ffeathers — a technical writer’s blog

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: