Preface: I am just as guilty at this
So, here I am at last, the end of the long 3 months of coding, testing and documenting an application written for 200 employees to use. At last a light at the end of the tunnel, at least I thought. My QA team consisted of 3 users who you could say is the average user base level with regards to new application experiences and they are very familiar with the old way of performing the task this application replaced.
Now a few more users have been added to the mix, immediately after they start to use the application, they approach me with tons of questions. In every case, the questions relate to what the documentation covers on pages 2 and 3… (step by step).
So once again, I bring my thoughts back to what is known as the ‘black hole of manuals’. What entirely is the purpose to us spending hours on end creating user manuals when we ALL know that they will never get looked at? I have come to the general conclusion that us developers generate manuals for one purpose. That purpose seems to be soley for our own amusement. We are all daft enough to think how great and accurate the manuals are and how easy they are to follow.
In the end, they are for sheer reflection. For those who create the program to be able to go back and ask themself years later, what on earth was I thinking to begin with…
I guess the only point to me posting this is to mentally vent… Back to training…
LOL, just answer all questions with “RTFM”.
Vent on!
The neat trick is writing your program so that manuals are unnecessary (or as close to unnecessary as possible). It’s not possible for really sophisticated products, but for training software it should be.
There’s a great story in Tog on Interface – I paraphrase from memory – about a training program that Apple included with the Apple II. There were two versions of the program, one that was designed for monochrome displays and another for color displays. The computer had no way of telling what kind of display it was hooked to, so the first thing the program did was ask the user whether they had a color display.
So they tested it on a few users and about 50% of users answered the question incorrectly. The problem is that monochrome displays were usually GREEN or AMBER and the question was displayed as WHITE text on actual color displays. So they rewrote the code so it displayed a bunch of colored circles above the question and rephrased the question: are the circles above displayed in different colors?
Now they had about a 25% error rate. Turns out that some users considered “nearly black” green and “bright” green to be different colors, and so on.
So they displayed three colored circles and asked users if the circles were three different colors. Now they got 100% correct and shipped.
As Tog points out, this was shipping to literally MILLIONS of users, and it’s a TRAINING program. If they screwed it up for even 1% of users, that’s a lot of irate customers on the phone. It seemed like a perfectly simple question, but assuming that it was simple would have been a huge mistake.
Even “typical users” who see a project during development will get too close to the project to be suitable “typical users” for final testing.
The irony to that story and this vent of mine, is that my control factor is a user who is very fond at being a very distinguished ‘spotter’ of issues. Now, granted, 9/10 programs, she nails anything that would be mentioned during initial use of any program I release. This program was so automated and intuitive that she barely had any change requests to make it any easier to use.
For instance, when it starts up, it is by default in a new document entry mode. All fields are empty, all select boxes are empty, the document windows are empty, everything is blank and ready. Clicking on File / New / Blank does the same thing, whipes out anything on the screen and prepares all back end data for initial use.
One of the very first questions I got which is covered on page 2 of the manual, is “how do I create a new document”… Ok, the manual says right off the bat that when the program loads, you can begin since you are already in a new document. Then it covers clicking on the file menu, the new and the blank options with what to expect when you click on blank.
My favorite question so far today is, I clicked on Blank and there is nothing in the boxes… Lovely…
Very vivid problem, since that is what was supposed to happen. All items that should be empty are empty. My second favorite question would have to be “how do I add items to the document”, (another notated item in the manual), the least of my favorite is “how do I save the document in progress”, that one is a fun question since all the answer to them would be “you don’t, it is done for you automatically”.
I honetly think my mistake is that I made the system way to automated and way to easy to use. Is there such a problem?
Honestly, I don’t think it’s so much that the user might not actually read the thing is what makes manual writing such a tiresome task.
The problem seems to be more about people who view themselves as intelligent being force to dumb down what they know in layman’s terms so anyone can understand it. In some sense, one might consider the task demeaning, as it forces them to both think like and consort with people they feel are less intelligent than they are.
For example, are you one of those people who often end up being the computer fix it tech for your entire family? After a few years, the task grates on the nerves as it wastes your precious time having to explain how to bring up a certain window, empty the trash or make some icon “go away”.
i don’t blame developers for not wanting to document their own software. But really, who else actually knows how it works besides you? Without you personally providing support, a lot of users would end up lost or frustrated to the point that they just give up on using your program. It’s an evil that must be done for the sake of completion. Even if no one reads it, the fact that a manual even exist will make the user a lot more comfortable with your software.
I think one of the hardest issues with any documentation, manual or text book is making the material relevant before one is finished reading.
The only manual I can ever think of having read was the Unity manual, and that was because I wanted to get into the application and know what I was doing, but I couldn’t spend time on the box. My train commute could only be filled with paper printouts, so I actually read a manual. :shock:
But it didn’t help. When I got done, I didn’t know what I was doing. It still doesn’t help. I still don’t know what I’m doing…
… or do I?
Learning anything takes that magic mix of education (self or otherwise) and practice. I’m so glad I did read that manual, because when I’m stumped I sometimes know where to look, and when re-reading some part of it, it can suddenly make sense and sticks. Reading the manual didn’t tell me how to build a game in Unity. It did, however, give me some of the many building blocks I needed, and am still needing and accumulating, to be able to master this application.
It’s very hard to write a manual that covers all of the aspects that are needed, and that is relevant to the problem at hand as the user plows head first into a new application.
In this era of constant unrelenting change - even for the better - people just want to move on and be productive. This often means that an employee doesn’t want to learn an entire new application. They just want to have their immediate problem solved, and solved fast. Unfortunately this usually means a trip to the help desk or opening a ticket rather than stabbing at a manual for a solution, and for the poor bastard that has to man it, it’s a nightmare.