Looking for guidance on writing tutorials for users

Question

Hi,

We are developing a desktop application.We are writing tutorials for users in a wiki.I was looking for some guidance ..good practices when writing such tutorials.

regards

Answer 1

I think some basic rules are ok

• include as many screenshots as you can
• don't use too much technical wording
• structure your pages/documents that it is easy to navigate inside
• don't make the user looks stupid, i.e. way of writing that would say the user is not capable of doing anything

Also it could be a good idea if you make your wiki and ask one typical user to review it with you. Getting the opinion of the user would probably show you million of things you have forgotten.

Answer 2

make sure your app is intuitive first. then when your sure it is, make it more intuitive.

see :

http://www.discoapp.com/
http://www.utorrent.com/
http://handbrake.fr/
http://www.nethack.org/

dont see:
http://www.adobe.com/
Windows songsmith

Answer 3

1. Have a FAQ
2. Tips and Tricks Section.
3. Have short videos about "How to..."

Answer 4

A few tips for technical documents:

1- Assume everyone reading the document is the dumbest person you've ever met who has never seen a computer in their entire life.
2- Don't skip a single step. Even if it's clicking a well-known button, etc. If your instruction doesn't start with "click" or "type", it's not granular enough.
3- There are never too many screenshots... unless you can't read the text between them, or fail to notice it entirely. Leave enough spaces between screenshots and text, and make the text one size larger if need be.
4- Do it yourself, multiple times. Make others follow your directions. Make your grandmother follow them. If she can, your manager probably can. Maybe.

Answer 5

Figure out the key features that users will use most often and provide a cheat sheat. Download any one refcards from dzone.com as an example.

Answer 6

I think the best tutorials are those that guide the students in an incremental, step-wise manner. Clearly describe prerequisites at the top and tell the readers 1, 2, 3 this is what you have to do.

Answer 7

• Choose your tasks thoughtfully (and stick to them). Each tutorial should cover a single task and stay focused on the goal throughout, with only the briefest digressions to introduce new terms or concepts. Start with the very first step a user needs to take to do something useful with the software. With a well designed app, a sequence of introductory tutorials is likely to start with a very short, simple one ("Creating a New Project") and proceed through intermediate ("Importing INTERCAL-72 Files") to advanced topics ("Customizing the Compiler Toolchain") so that the tutorials become more involved as the user becomes more involved with the app.

• Use numbered lists. Describe specific procedures that can be followed by anyone who can read.

• Use consistent styles for program and interaction elements, like bold text for buttons and menu items and monospace fonts for user input. The specific styles you choose matter less than their consistent application. If we're talking Windows apps, the Microsoft Manual of Style for Technical Publications might come in handy.

• Verify your procedures relentlessly. If a user needs a tutorial to figure out how to use the application, she's probably already frustrated. If she follows it to the letter and it doesn't work, everyone's a lot worse off, including you and your support rep.

• Use screenshots as signposts. Include one screenshot of each window and dialog box referenced by the procedure. Don't label them or otherwise doll them up. They're there to provide visual reinforcement that the user is following the procedure correctly and getting to the right places.

• Respect different learning styles. Keep in mind that most people are visual and/or auditory learners, so text isn't the best way to reach them. In practice, that means screenshot videos with voiceover. The written tutorial is the script.