Hi Charles,
Well, yes and no. I've certainly seen my share of good manuals, but I've also seen my share of confusing, complicated, or down right poorly written manuals as well. The problem for anyone writing a manual is how much to say in the manual, what needs to be said, and how much can safely assumed the end user knows. For example, some of the most difficult manuals I have had to read is programming API reference documentation. These are not step by step guides, but a set of documents explaining every function, library, etc contained in the technology. They have sample programs, but they don't always get into a lot of detail how this or that works, and assume you are fairly familiar with the programming language and various concepts being discussed. That is why it can be very difficult for a new programmer to learn how to be an effective programmer. The documentation and often the sample source is written for a skilled or advanced programmer, and a beginner finds him or herself out of their depth. Take DirectX for a moment. That is a fairly complex, highly advanced, technology for Windows. Never-the-less the documentation that ships with the 9.0C SDK is written at a fairly advanced level, and takes a lot for granted.

A. You are a skilled C++ developer.
B. You understand key Win32 API concepts.
C. You own and know how to use Visual C++.
D.You will understand the code samples included in the documentation.
E. There are other sources for A, B, C so no need to repete previously written documentation.

As I said this takes a lot for granted, and assumes the end reader is a fairly advanced programmer to start with. if someone fresh out of college takes a look at some of the code exampls, the documentation, etc as I did a few years back when starting to write games he or she can get lost, confused, etc very quickly. In the end the only way I managed to make heads or tails out of DirectX was by purchasing some beginner books on the topic which explained the technology in down to earth language that I could digest and understand. Once I understood the key/core concepts then i could go in and read those API reference manuals and have a clue what I was looking for and what exactly Microsoft was trying to tell me. At any rate writing documentation for a game is not as complicated, but the point is the same. What should a developer say or not say when writing that user's manual? When I write a guide for say, "Mysteries of the Ancients," I need to cover the entire product. However, I assume the end user has some knowledge of basic computer skills such as how to use his/her screen reader, that they know how to download files from the internet, they know how to locate downloaded files on their computer, and they know how to access icons from their start menu on there own. I suppose to a brand new blind computer user that is a lot of assumptions, that I am asking for skills currently out of his/her experience, but then again I'm not there to train them how to use a computer. I'm there to document my product and how to use it. Usually this is fine for the average customer, but now and then there will be someone totally clueless how to do the most basic computer skills, and then the manual will get blamed for leaving something important out. At least something they felt was important or would have been helpful to them. On the other hand putting too much information in a manual can be just as bbad. It may help a totally new user of a product get started using the product, but will be quite tedious to someone more experienced. There is such a thing as too much information, and the end result is a very long, boaring, and tedious read. Most software companies assume you have some basic skills with the computer such as downloading programs, knowing where you downloaded the file to, how to use your screen reader, bla. The companies assume if you don't know those things then read some basic computer manuals before returning to their product. Honestly I can't blame them, because it costs time and money to document basic skills the end user should already possess at the time of purchase, download, whatever.

Charles Rivard wrote:
> User's manuals are often blamed for some of the problems that people are
> having.  Then again, it is found that people often don't read them.
> Manuals are written by people who know what they're talking about for
> those that don't.  Think writing one is easy?  Give it a try.  In your
> spare time, write the user's manual for something you have in your
> house, such as a home stereo, CD player, or even, yes, a computer game.
> Don't leave anything out, but make your manual understandable by someone
> who does not know the device or product you are talking about.  Be
> patient with the user and go slowly in describing.  Here's one for you,
> write a user's manual for a cell phone that can guide a blind person
> through it's operations easily and in a way that will not confuse them?
> I dare you.  If you try this, you'll be able to see the problem from
> both sides of the issue.  Remember, the reader does not know anything
> about what you're trying to teach them how to use.
>

---
Gamers mailing list __ Gamers@audyssey.org
If you want to leave the list, send E-mail to gamers-unsubscr...@audyssey.org.
You can make changes or update your subscription via the web, at
http://audyssey.org/mailman/listinfo/gamers_audyssey.org.
All messages are archived and can be searched and read at
http://www.mail-archive.com/gam...@audyssey.org.
If you have any questions or concerns regarding the management of the list,
please send E-mail to gamers-ow...@audyssey.org.

Reply via email to