views:

219

answers:

11

Documenting for end-users is hard because read documentation sucks if you don't use to do it. And if you want to push the end-users to use it, you need to look for the easiest way.

I guess that the best way to document is using screen recordings. Do you agree? Do you think there are better one?

+2  A: 

You should consult your potential end-users for input on what might be gainful to them. Perhaps ask what pitfalls they have encountered in the past with similar software.

Also, a wiki could certainly be advantageous so that the documentation can grow when questions arise. This will help the documentation better meet the needs of your end user and be able to grown and change with them.

eleven81
+6  A: 

I try to provide as much context sensitive help as I can because I figure people won't read the manual. I've also done some screencasting for training purposes.

EDIT: and I make the UI as intuitive and simple as possible.

tvanfosson
A: 

We're using videos of common or complex operations with great success. They are easy to make these days. We use Camstudio.

Jim Blizard
How do you update your documentation when something is modified on the interface? Do you recreate the whole video for a recolored label or one new button?
rics
This is a problem that plagues Microsoft, check out the ASP.Net MVC videos for example, the Syntax isn't even the same and will most likely never be updated.
Tom Anderson
+1  A: 

I think screen recordings are a great way to create end-user tutorials, end-users really love the step by step approach and doing this with printscreen is a mind numbing job. However video's don't seem to work well on printable media ;)

Do lots of screen recordings showing your application off by all means but treat them as extra tutorials and not the core documentation.

Stick to text and pictures. It's way more portable.

Martijn Laarman
+2  A: 

Everything is easier to follow in comic book format.

Dan
A: 

Using things like Camtasia Studio to document software can be a great instructive aid, and they can also work as decent advertising.

However, the problem with videos for documentation is that they are very difficult to search. It's tough for the user to find out how to do a specific thing unless there are a LOT of very small videos that are very well labeled in some other place.

And, just like manuals, you can expect that the user will not watch the videos BEFORE they use the product.

Videos can be a nice help but I feel that text documentation is still most useful for when someone wants a specific bit of information.

You might try using text explanations that reference specific videos or a specific time within a video.

TM
+1  A: 

Depends on your end-users. If your end-users are programmers, probably some form of text documentation with technical language would suffice. If your end-users are mom and dad, then screen captures are generally better.

So basically, if your end-users are beginners to computer, they would need strict rules, and hand holding, and less digressions that would confuse them. As they become more proficient, they would want something a bit more free-form, so that they could put together thing that they wnat to do.

Calyth
A: 

One thing that actually got me to read the help documentation was the way that Office 2007 implements it integrated into the User Interface.

With one of our applications we added little links throughout our wizards like "What is a concept?" or "What should I do?", when clicked the help topic was shown in a custom form with some basic HTML support.

Our documenters use a custom application to build the documentation that simply compiles it to a resource assembly in .Net.

Simple help files and Adobe docs just don't cut it in most cases, people aren't going to read these huge documents to find out about what that one text box "really" means.

Tom Anderson
+1  A: 

The less the better. Nobody reads boring documentation anyway. The system should be intuitive enough not to require any documentation, otherwise people won't use it. For really advanced functions, use some kind of context-sensitive help, or put the text on the form where the options are.

erikkallen
+1  A: 

Just in time help, something beyond the usual brief text based definitions. Provide practical examples of doing daily tasks. Screen captures are good, screen movies are better. We use WINK a decent freeware motion capture utility that produces flash movies.

Jim C
A: 

I think documentation should be integrated with the user interface as tightly as possible: it is better for the users because the mental mapping between them is easier and there is no need to switch contexts, and it is better for the developers because it is easier to avoid redundance and to prevent them going out of sync.

thSoft