Example of simple documentation

Minimal text. Big friendly arrows. Partial screenshots. Is this one example of what a simple document looks like? How to Edit the Atlassian Developer Documentation.

Over the last few months our team has been asking itself what constitutes simple documentation. As any technical writer will tell you, answering that question is not a simple matter! In July I wrote about one product manager’s response to the question: What makes simple documentation. A number of people responded with some very interesting comments on that post.

Is this a good example of simple documentation?

Now here’s an example of a document I’ve just written. It is aimed at a specific market (community developers who want to contribute to our documentation) and describes a fairly simple task flow (how to find the edit button on the documentation site, save a draft and then publish your changes).

My aim is to get people started as quickly as possible and give them enough pointers that they can figure out the rest themselves. The readers are a savvy bunch. They know what they want to do, and have used many different types of editors. So I’ve gone for:

  • Minimal text.
  • Bold sequenced steps.
  • Partial screenshots, with enough context to orient people.
  • Big friendly arrows pointing to the relevant control.

Here’s how the document starts.

1. Log in

Login

2. Search for or click through to the page you want

Search

Use the search box to find the document you want.

Alternatively, click through to the page you want:

Docs

Click the ‘Docs‘ tab.

Pagetree

Click through to the page in the left-hand navigation panel.

3. Hover near the title and click the edit icon

Edit icon

  • Move your cursor to the top left of the page’s content panel. The edit icon (two crossed pencils) will appear.
  • Click the pencils.
  • Make your changes. The wiki is running Confluence 3.5 with wiki markup.

The rest of the page

And so on. If you like, you can take a look at the real page: How to Edit the Atlassian Developer Documentation.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 1 October 2011, in atlassian, technical writing and tagged , , , , , , . Bookmark the permalink. 14 Comments.

  1. Kudos Sarah for taking on the unenviable task of defining “simple documentation” (with examples, no less!).

    It’s always going to be a moving target. I think it’s great, but I wonder if this couldn’t be distilled down even further to essential points plus a video showing everything (that may or may not even be needed by your readers).

    Perhaps something like:

    —–

    *Editing the documentation*

    Click Edit (png of icon) to edit a page in the documentation. You will need to be logged in to the site first. Site accounts are free, all you have to do is [sign up|linky to sign up page] for one!

    [short video of sign-up, page navigation and editing]

    *Signing up for an account*

    Click Log-in, then Create an account by clicking the [Create Account|linky to sign up page] in the upper-right corner of the page.

    [link to save video as above. Remember, it starts with sign-up]

    —–

    Amongst about a million other things, the above presumes that the more sophisticated audience of developers don’t need step-by-step instructions for logging in or browsing a website.

    I’m not quite sure if a sep. topic for sign up is even needed, but perhaps it’s good to have for the purposes of search.

    I guess what I’m wondering is: Is it worth it to go really minimal for this audience?

    • Hallo Michael

      Thanks for a great reply! I think you’re right: I should go even more minimalist. It’s a good idea to remove the screenshot of logging in, replacing it with just a few words. I’m going to skip the videos, because I’d like to keep the process of following the instructions linear (apart from the link out to signing the contributor’s agreement).

      We do need to tell people how to edit the documentation, because the process is different from the usual easy wiki “click edit -> save”. People can’t see the edit icon unless they know where to hover their cursors, and there’s no save button. I’ve already had a number of very savvy developers saying, “Sarah, how do I edit anything on the new site?”

      I’m going to edit the page right now, to make it even shorter.🙂

      Cheers
      Sarah

  2. A useful compromise that we have used is to put the screenshots in dropdowns with a hotspot of “Show me the screen”.

    • Hallo Peter
      That’s a great idea! Especially for the latter part of the document, which is a collection of frequently used actions rather than a sequence of steps. I’ll give it a go. Thanks.🙂
      Cheers, Sarah

    • Following up: I’ve asked our developers what they think about the idea of hiding the screenshots in expandable sections. Opinion is divided (who’d a thunk it) but there are enough people who prefer to see the screenshots out in the open, for me to think I’ll leave them visible. It does make for a simpler page if people don’t have to click to see the images.

      Of course, this is a very specific document with a very specific audience and purpose. I want people to be able to scan the page, see the bit they need and move on quickly. As always, a different requirement will lead to a different decision.

      Thinking about a slightly different topic: This comment is a good illustration of why style guides need to be flexible, providing guidelines rather than rules.

      Cheers, Sarah

  3. We’re working on a similar initiative at my company and you’re right; this is not a simple question to answer. We’ve decided to address simplicity by documenting ONLY what is relevant for the particular business problem being addressed. Instead of documenting every field, option, or value on a particular dialog, we’ll describe only those needed in each scenario.

    I’ll let you know how it goes, as I am just starting a brand new project using this method.

    • Hallo Patty

      Very interesting! What you describe is one of the directions we’re leaning towards as well. The other direction is the style and length of the pages.

      It will be fascinating to see how it turns out. I’m looking forward to seeing your results, and I’m guessing you will blog about them.🙂

      Cheers, Sarah

  4. The problem with “simple” is that it usually isn’t simple to define without qualification. Saying “the documentation is simple” or referencing “simple documentation” can refer to any number of things…

    Is it, “simple to read?” …which suggests a certain approach to presentation and perhaps even constraints on syntax, diction and grammar.

    Is it, “simple to understand?” …which suggests an efficiency of comprehension, and dependent to a large part on what knowledge the reader brings to the page.

    Is it, “simple to maintain?” …which can often mean a limit of scope and feature coverage.

    Is it, “simple to find my answer?” …which may mean easy to use search functionality, content navigation and more comprehensive scope that includes a healthy mix of conceptual, reference and procedural topics.

    I like to think that a given approach can meet multiple of the above, but I think it’s important to remember that “simple” != “useful”.

    • Hallo Michael

      Yes! Nail on head.🙂 There’s also “simple to look at”, which is sometimes the overriding concern when we’re talking about “simple to find my answer” on a single page. In other words, people should be able to scan a page and find what they want immediately.

      And I think there’s “simple to follow”, when talking about step by step instructions. A lengthy “how to” page may appear quite complex, but it’s just the ticket for someone who needs to follow a complex procedure step by step.

      In a nutshell: The meaning of the word “simple” depends on the type of document we are writing.

      Cheers, Sarah

  5. Hi, Sarah! Yesterday I saw a nice example of _really_ simple documentation – http://onepicturetutorial.com
    The guys (a very small company) make an IDE for ActionScript, and all IDE smartness is usually not “on the surface”. So every day they post a picture optimized for “iPad reeding”, explaining just one feature.
    I think everyone’s typical workday starts with a cup of coffee and some kind of news reading… and here comes their simple documentation!

  6. Simple and minimal aren’t always the same thing. Important to remember…

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: