How do I create an awesome user manual and training series?
April 26, 2014 3:55 PM   Subscribe

As part of my job, I've been tasked with developing a user guide for an open source software package that my company developed, as well as future webinar (and possibly in-person) training materials. Is there a good source for finding industry best practices for user manuals and tutorials? I'd like to see what the most innovative organizations are doing when it comes to training materials.

Google has led me to the Society for Technical Communication and but I am having trouble finding specific examples and detailed best practice guidelines.

I could use help identifying:
- Different ways to organize information in a manual. For example, should I start with very basic instructions and then build complexity with each chapter?
- Best practices for creating webinars that don't put people to sleep.
- How to plan long-term for also creating more detailed developer documentation.

Two books that look promising are Design For How People Learn and Essentials of Online Course Design: A Standards-Based Guide. However, I wanted to check with the wise people of Metafilter before embarking on an Amazon spending spree. Would you recommend either or these books or other ones? What other resources should I be checking out?

Thanks in advance!
posted by JuliaKM to Education (6 answers total) 23 users marked this as a favorite
Check out the documentation for MongoDB. That is some gold standard docs.
posted by ch1x0r at 4:40 PM on April 26, 2014

The first step (not being snarky here) is to understand the difference between a user guide, developer documentation, and tutorials. Technical writing and instructional design are both their own professions. You are asking for (at least) the Cliff Notes to two different professions, as only part of your job? You need to (looks at tags and sees "helpdesk" -- seriously, that too?) narrow your question.
posted by Houstonian at 7:29 PM on April 26, 2014 [3 favorites]

I had to wing writing a user manual once for some software back when I was very young and had no training in technical writing yet.

I gave drafts of everything I wrote to my dumbest, most computer-illiterate coworker and watched her work through various tasks using the software and my manual. I didn't tell her that I picked her because she was the dumbest, of course -- I think I buttered her up with some praise about how she was one of the most helpful people there, etc.

It helped a LOT in figuring out where I had been unclear. For example, I found that I couldn't just refer to menus and functions by name because she couldn't grasp the concept of hovering the mouse over things to see the tooltip to figure out what they were named. So I used screen caps and MS Paint to cut out little pictures of the icons to insert next to every reference to which menu, button, etc. to click. This worked much better for her because then she just had to match the picture in her manual to the one on the screen and click it.

So, if you can find a diplomatic way to recruit someone really dumb to help test-drive your drafts, I highly recommend this tactic!
posted by Jacqueline at 8:10 PM on April 26, 2014

If you're writing docs for other programmers to use your package, try this guide.
posted by batter_my_heart at 9:37 PM on April 26, 2014

Check out the documentation for MongoDB. That is some gold standard docs.

If you like the layout of those docs, check out There are lots of links there to other open source projects that use this service, so you can look at how other people organize their documentation. If you host your code with Github or Bitbucket, you can have your docs get rebuilt whenever you push updates to the main repository.
posted by Blazecock Pileon at 11:59 PM on April 26, 2014

People rarely sit down and read the manual (or other documentation) from front to back. They want to get some specific shit done now. They go to the documentation only because they can't figure out how to make the software do X or how to make the software stop doing X when it should be doing Y.

As such, the order of your thousand task-specific topics is not as important as letting readers go straight to the only topic they need right now to get that one task done. Search and indexing have to take them straight to the best answer. Test the shit out of that: using just the search box or index and all the likely search strings you and others can come up with, can you find the right topic to get each job done?

Even when you're writing a topic that doesn't seem like a task (how to do something), think of it as a learning procedure (how to understand something). Take them step by step through the process of understanding something they need to know to use the software.

If you write all of your stuff as standalone tasks, you can easily reuse them in various ways for your user guide, help system, tutorials, etc.
posted by pracowity at 4:12 PM on April 27, 2014

« Older Looking for (not so) big adventures on Kauai   |   What should we do/eat/see in Kyoto? And should we... Newer »
This thread is closed to new comments.