Mail Archives: djgpp/1998/02/11/22:01:13
>This is partly off topic but I think it is important:
I think it is very much on-topic. This newsgroup exists mainly as a
forum for technical support, so it is important to consider ways of
making that support better, or of improving the documentation to prevent
people having problems in the first place.
>There are different kinds of people posting questions on the newsgroup:
>
>Of course there are people who ask "how do I install djgpp" because
>they are too lazy to read even the "readme.1st" file.
There are certainly some people like that, but I think a larger
contingent are the people who just assume that the docs are not
important. I certainly do that myself often enough: if I have just
downloaded a game off the net and I see three files called readme.txt,
setup.exe, and game.exe, I would probably just run setup followed by the
game, and ignore the readme altogether. But I don't understand why, when
they run into problems, they don't then go back to read the
documentation. Maybe people just download the zip files because they
think the readme is not important, and then they have forgetten about it
by the time they come to actually install it on their PC? Or perhaps
they have failed to notice the readme at all?
It would be very useful if someone who has made this kind of mistake
could tell us _why_ they made it, and what could have been done
differently to make sure they actually found the information they
needed. It is impossible to improve things without first understanding
exactly where people are going wrong!
>There are, conversely, many people who *read* the docs but *are not
>able* to find what they need. This can be because the people who write
>have often very different ways of reasoning from people who read, or
>simply because they could not join the different pieces together.
Of course, there will be some such people. No documentation is perfect,
although I think some of Eli's stuff is coming quite close :-) But even
if a file can be clearly understood by nine out of every ten people,
there will always be someone who just thinks in a different way to the
author, or who lacks some essential bit of background information, so
they will find it confusing.
I don't generally mind answering questions from people who are honestly
confused, no matter how obvious the answer might seem from the
perspective of someone who already knows it. I might not be particulary
verbose in my reply, but I will politely point them towards a source of
the information. The problem lies with the people who are just lazy: you
would be amazed how many mails I get that run along the line of "I want
to make a game, but I don't know how to program, can you please teach
me?" :-) It is usually quite easy to tell which is the case (it is the
difference between someone saying "I can't make it work" and "I don't
understand what the readme means when it says to do XYZ..."), but I'm
sure I sometimes get this wrong, and I apologise if I have ever sent a
less than polite reply to someone who had already made a genuine effort
to solve the problem on their own.
The thing is, I think the world contains a lot more lazy people than it
does confused ones. Every time someone complains about not being able to
find some information that they need, Eli asks them for suggestions
about how the docs could be improved, but as far as I can tell very few
people actually come up with ideas for this. If they had already looked
through the docs and just got lost, I think they would have a pretty
good idea how that could have been prevented. They would know exactly
how they tried to find the info, so it would just be a matter of
changing the layout to make sure their searching method would work in
the future. To me, the fact that so few people actually make this kind
of suggestion implies that they hadn't actually looked very hard in the
first place!
Some people also complain that the djgpp documentation assumes quite a
lot of background knowledge and uses jargon that they aren't familiar
with. It is certainly true that the docs assume you are a competent
computer user, familiar with DOS, and that you have and know how to use
a text editor. But I don't think the readme or FAQ are the correct
places to cover this kind of material: it seems reasonable to assume
some familiarity with the machine you are using. Maybe there would be a
role for an "everything you need to get djgpp up and running without
ever having used a computer before" tutorial: any takers to write such a
thing?
>>If you have specific suggestions on how to let the existing knowledge
>>more accessible to users, please go ahead and tell what do you
>>suggest. Personally, I invest a lot of effort into making the FAQ
>>more easily searchable, but I'm always looking for better ideas.
>
>Well, personally I found what I wanted everytime I looked at the FAQs, so
>I don't know how to suggest... maybe it could be useful some sort of index
>of keywords ?
I rest my case :-) Where are the people who have actually tried to find
something in the FAQ and been unable to locate it?
--
Shawn Hargreaves - shawn AT talula DOT demon DOT co DOT uk - http://www.talula.demon.co.uk/
"Pigs use it for a tambourine" - Frank Zappa
- Raw text -