Re: [Audyssey] manuals - Re: I give!!!!
Hi Thomas, I have and had the same problem with programming manuals such as for DirectX. I just don't understand them at all. Allen Maynard shared some DirectX code with me, if it weren't for that I probably still would not know how to use DirectX. You know I have really never been able to learn from manuals. Well except for the manual that came with my first computer, the Texas Instruments 99 4A. But even that was just that I typed in some example source code and experimented with it. So really example source code from here and there and experimenting with it is how I have learned to program games. BFN Jim I didn't get the documentation for the manuals! j...@kitchensinc.net http://www.kitchensinc.net (440) 286-6920 Chardon Ohio USA --- 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.
Re: [Audyssey] manuals - Re: I give!!!!
Hi, You said: the 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. I did. I'm talking from experience. I spent 3 months re-writing the jaws 4 manual. Because the guy who I was teaching to use it actually couldn't get to grips with it. So I rerote it and went so far back to basics it would bore the likes of you and me but for someone like him it was necessary. I didn't do it alone. Assisting me I had people who new about the programme, people that taught others how to use it, people who have herd of it but have never seen it or used it. It's foolish to believe that even though I'm the one writing the manual, that I'm going to have a 100% perspective as to what needed to be done. Thus I chose to do it in the way that I did. I was doing all the work, I was sending them via email all their submissions and based on their feedback I would make changes. Or explain why I had written a given thing and accept or reject any advice they gave me. So I'm sorry Charles but yes I will say that a lot of problems that people have, is because of the way that the manuals are written. It's very difficult to go right back to basics and not many people see the benefits of that. The vast majority of manuals I look at now I'm so critical of them you honestly wouldn't believe it. Some of them I can honestly say have left me cringing. Because if the manual is thus badly written what does that say for the product itself? All that time and energy gone into developing that product for it to be let down by it's user documentation. The long and the short of it is, it's all well making sure that your product works, but if you aren't going to spend the time required on the nuts and bolts as in the user documentation, then you may as well not bother at all. If people cannot just pick up and get to grips with something, then a lot of the time they will just put it down again. Because half the problem there is a psycological one. Oh it's me that is stupid I can't understand this bla bla bla. This is where a lot of your fobias actualy come from. And the tech support lines are loving it because you're calling them, being charge a stupendus amount for the privelage just to solve a problem that could have been easily solved in most cases if the manual was written in a way that it was understood by who ever read it no matter from what background. You said: 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. This is in part true. But also it is true to say that considering how in the majority of cases, manuals are written in such a poor fassion, people just don't seem to waste their time on them any more. Just how much is released these days that is just so full of bugs and stupid stuff like that? Not enough time is spent on development of a product and the user documentation is just as much a pert of that development. The quality of work in many ways has slowly and surely gone down hill over the last few years in general. -Original Message- From: gamers-boun...@audyssey.org [mailto:gamers-boun...@audyssey.org] On Behalf Of Charles Rivard Sent: 30 March 2009 03:03 To: Gamers Discussion list Subject: [Audyssey] manuals - Re: I give 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
Re: [Audyssey] manuals - Re: I give!!!!
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
