10

Our in house software has been used for many users and the training department asked us for any tips of end user documentation format.

Does any know where can I find good examples of software end user documentation that a training department to use for inspiration or any sites with good advise?

This is similar to this question however I am looking for end user documentation for use used by non-technical users.

Improve this question
8
  • 1
    "where can I find good examples of software end user documentation" Step 1. Buy some software. Step 2. Read the documentation. What's stopping you from picking up documentation from existing software you're already using? I believe that most end-user packages have the complete documentation on-line. What's stopping you from reading Microsoft's documentation for their Office Suite?
    – S.Lott
    Apr 26, 2011 at 12:00
  • I believe most of the documentation I have read is written in a way not that is not appealing to read, and most of the books I have are generally programming related aimed at technical audience. Just see when anyone last read the Microsoft manual? Therefore I was looking for some inspirational examples.
    – John
    Apr 26, 2011 at 13:01
  • Hmm, interesting q.
    – Rook
    Apr 26, 2011 at 13:57
  • @John: "most of the documentation". Okay. So, after discarding "most", what's left? We don't know why you're rejecting some of the most-used documentation on the planet as "not appealing to read". You might amplify your list of complaints, and add your personal short list of examples of software documentation that isn't excluded by your "not appealing to read" test. We don't know you very well, so we can't guess why you mean by "not appealing to read".
    – S.Lott
    Apr 26, 2011 at 15:19
  • 2
    Let's be careful that we don't require questions with such specific criteria of what is "good" that it becomes to localized and not applicable to most people. I'm not interested in color schemes.
    – JeffO
    May 2, 2011 at 13:51

5 Answers 5

Reset to default
1

You might want to start by interviewing your in-house users about the software, and find out what kind of information they would want to know.

Much of the documentation I have written about software has had one or many audiences in mind. Your training department probably would benefit from a skeleton of topics (like a TOC). So then you could discuss what topics are relevant and what are irrelevant to their training objectives.

Some of the topics could cover:

  1. Target Audience(s)
  2. Technical Requirements
  3. How to Install (if applicable)
  4. Process (i.e. what business function does the software perform?)
  5. Featureset (what features does the software have?)
    • You could have a task based approach to this, e.g. Add A User or Add a Document
    • You could have an object-based approach, e.g. Users, Roles
    • You could have a Menu-based approach, e.g. File menu, View Menu
  6. Lastly, possibly a Upcoming features and FAQ section might act as a growing knowledge repository of your product.

Try to anticipate how your end users use your software, based on your knowledge of developing it, your knowledge of what it does and also based on (hopefully) your interviews with end users.

Most importantly, try to make documentation that you would want to read, use fun example names to demonstrate, and use lots of annotated screenshots.

Hope this helps

Improve this answer
2

I have read several "End User guides", and wrote one, and I think that there are many elements that improve their effectiveness:

  • Show with images how is issued some command, or made some action (screenshots for example).
  • Focus on the need to do something, and the way to get it done. Stay away from technical descriptions about how optimized is that action done for example.
  • Once I put a flow diagram describing the modules the software was divided, and I received comments that it wasn't very useful.
  • Try to foresee the possible problems a user may have, so that your Troubleshooting section gets useful. You must also test your program with users who were not involved into it's development, even your coworkers that woked on other projects.
  • Avoid boring descriptions. Any further information may be put into an appendix or something like that.

I hope this may be useful for you.

Improve this answer
1

You mention that it will be used for training.

If you're looking for a training document rather than a reference document, my favorite such site is Joel Spolsky's tutorial on Mercurial here.

  1. Simple, clean presentation. It's nice to look at.
  2. Authoritative, but personal in tone. It feels like you're in a great college lecture.
  3. Simple pictures, not copious amount of actual screen shots. Read The Back of the Napkin for why this works.

If you're training document were 1/2 as cool as Joel's Mercurial tutorial, I'd read it. But you need someone with a) a passion for writing and b) an incredible depth of knowledge to pull it off, even if you could copy the 3 points above. Hope it works.

Improve this answer
0

I don't know if this possibly fits your needs, but there are systems out there used for technical documentation sphinx being one that comes to mind that facilitate creating an online documentation. Could something like this be used for what you are interested in?

I also just ran across ReadTheDocs which does much of the same thing but is a hosted solution.

Improve this answer
0

Check out the Society for Technical Communication (STC). Many of their award winners wrote production that is generally available. They may also have samples available. Becoming a member will also provide access to a larger body of information.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.