Back in the day, the folks who brought us PONG got it right. Here is the user manual:
When is the last time you were given such succinct, yet usable instructions? Leave a comment.
It's been a while. So many manuals today describe the user interface in detail, but they never explain how to use the product. Here's how those instructions would probably look if they were written like a lot of the ones I see:
Pressing the joystick to the "UP" position causes the user paddle line to move upward. Pressing the joystick to the "DOWN" position causes the user paddle line to move downward.
Inserting a quarter causes the game to begin.
The paddle moves in an unintended direction. --- Make sure you are moving the joystick to the correct position.
Ball stops moving or does not start moving --- Ensure the proper amount of quarters has been inserted.
The Sun Solaris manuals take an interesting approach - they split a lot of it up into "Concepts" and "Tasks," where concepts would explain how it works, and tasks would describe the user interface in detail. The problem with this is that the concepts section is often way to long and detailed to quickly find the information you need - no one wants to curl up with a manual and read it cover to cover. I think Cisco has done a good job of making detailed, yet skimmable, documentation. There are lots of diagrams, so you can skim to find a diagram that looks close to what you're trying to learn. All the commands (user interface) are in tables, so you know where the "concepts" stop and the "tasks" begin.
I have to disagree with Tony Soper's admiration for the Pong user instructions: "Insert quarter Ball