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
- If you don’t yet have a username and password, please sign up for the Atlassian Contributor License Agreement.
- Click the login link and follow the prompts.
2. Search for or click through to the page you want
Use the search box to find the document you want.
Alternatively, click through to the page you want:
Click the ‘Docs‘ tab.
Click through to the page in the left-hand navigation panel.
3. Hover near the title and click the 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.
Posted on 1 October 2011, in atlassian, technical writing and tagged atlassian, minimalism, simple documentation, simplicity, technical communication, technical documentation, technical writing. Bookmark the permalink. 18 Comments.
ffeathers 
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
Wow! Pretty slick, Sarah!
And you’re right, always listen to your users… In fact, it’s usually best to listen to anyone but me. 😛
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
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
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
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!
Hallo sasha
That’s really cool. It’s a bit like a “tip of the day” in pictures. Ha ha, I like the typos, both intentional and unintentional too. Thanks for showing me this link! I think you’re right, the idea has great potential.
Cheers, Sarah
No typos! just a su-u-ubtle hint at http://itunes.apple.com/us/app/reeder-for-ipad/id375661689?mt=8 🙂
Simple and minimal aren’t always the same thing. Important to remember…
Pingback: How To Open Sphinx Source Files – JojoCms
Pingback: Referencing Classes Accurately And Concisely In Sphinx – EcoTravellerGuide
Pingback: Troubleshooting Sphinx Autodoc: Discover The Causes And Fixes For Your Files Not Being Processed – EcoTravellerGuide
Pingback: Generating Python Documentation With Sphinx: A Step-by-Step Tutorial – EcoTravellerGuide