From: Shawn Hargreaves Newsgroups: comp.os.msdos.djgpp Subject: Re: docs and ng posting (Was: Re: Newbie question, newbie error) Date: Wed, 11 Feb 1998 19:54:04 +0000 Organization: None Distribution: world Message-ID: References: NNTP-Posting-Host: talula.demon.co.uk MIME-Version: 1.0 Lines: 96 To: djgpp AT delorie DOT com DJ-Gateway: from newsgroup comp.os.msdos.djgpp Precedence: bulk >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