Example of simple documentation
Friday, 30 September 2011 22:15
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.
Read more http://ffeathers.wordpress.com/2011/10/01/example-of-simple-documentation/
