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 __ [email protected]
If you want to leave the list, send E-mail to [email protected].
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/[email protected].
If you have any questions or concerns regarding the management of the list,
please send E-mail to [email protected].
