Poll: Who Reads Documentation?
prof_braino
Posts: 4,313
Poll: Who Reads Documentation?
Data suggests that only about 5% (five percent) of the target audience actually reads the documentation.
Documentation is extermely expensive create, and can be very difficult to read. Perhaps the writers are not skilled, or the requesters cannot afford the activity. Perhaps we get conditioned to ignore the documents, or only turn to them as a "last resort" when all other "more productive" solutions do not satisfy. Perhaps we are conditioned to believe we are "really smart" and can just "grok" the material.
On the other hand, some folks (like me) have evidenence that we are NOT so smart anymore, and ALWAYS need to read the manual first. It just saves time, and I know where to go for the proper refrences when I eventually have to go "look it up". Am I just weird?
Please select one of the following, or post a more accurate description in the comments
Always read the manual first
Sometimes read the manual: mostly when I get stuck
Seldom read the manual: after I tried everything else, including posting in the forums, and somebody says RTFM
Never read the manual, what is this "manual" of which you speak?
other
Data suggests that only about 5% (five percent) of the target audience actually reads the documentation.
Documentation is extermely expensive create, and can be very difficult to read. Perhaps the writers are not skilled, or the requesters cannot afford the activity. Perhaps we get conditioned to ignore the documents, or only turn to them as a "last resort" when all other "more productive" solutions do not satisfy. Perhaps we are conditioned to believe we are "really smart" and can just "grok" the material.
On the other hand, some folks (like me) have evidenence that we are NOT so smart anymore, and ALWAYS need to read the manual first. It just saves time, and I know where to go for the proper refrences when I eventually have to go "look it up". Am I just weird?
Please select one of the following, or post a more accurate description in the comments
Always read the manual first
Sometimes read the manual: mostly when I get stuck
Seldom read the manual: after I tried everything else, including posting in the forums, and somebody says RTFM
Never read the manual, what is this "manual" of which you speak?
other
Comments
I always read the manual, but I really only finish the well-written ones.
With the advent of Microsoft Word and PDF paperless documentation, everybody is writing something. But where we once had editiors, copy checkers, and typesetters asserting some form of quality control, now we have tons of stuff that isn't really finished on the internet.... straight from the author to the public.
Parallax won me over very early on because it was dilligent and thorough in publishing the Basic Stamp Sytax and Reference Manual. It still is one of my most favorite microcontroller reference manuals as it is a cut above all the others I have have gotten. I had first bought a BasicStamp clone for one of Parallax's strongest competitions back in 2003, and was furious as their documention was junk. It seemed they had the deep pockets to buy a full page ad in Nuts and Volts month after month, but nobody could write and I have doubts they even finished their programing.
So, are you expecting me to read the bad stuff end to end also? First read the intro and conclusion to see if the writer has anything to say.
Actually, I consider this a very different context than computer programing or installing specific components. For instance, I never read an user manual for the first car I drove = my mom just told me where everything was. And I have not yet read the user manual for my 125cc Yamaha motorscooter as it is all in Chinese. With these items, I do just fine by asking someone for something.
The sad reality is more appliance user documentation show stay well under 50 pages, but with paperless PDFs, the documents have gotten excessive.
I bought a Canon SX150 recently and I have a 200 page PDF of drivel.
And I bought an HP Graphing Scientific Calculator (an HP50) that has a PDF of some 700 pages.
These documents are absurd and extremely pedantic. People generally want to read 200 pages or less of well-written material on any topic. And a new gadget doesn't really need even 50 pages.
Then there is the simpl3 fact that NOBODY every wrote a decent explanation of how to set the clock on a VCR, so everybody just got their 10 year son to do it via trial and error.
Style, Topic, and Context determine what people are willing to read. Most computer language books could be 50% shorter, and sell better.
If I'm assembling IKEA flat packs or such like it's not often I get confused enough to need to look in the manual.
As a teenager with a Yamaha motorcycle I read the workshop manual for that in minute detail. Even though I was not about to get into reboring the motor.
That manual, translated from the Japanese started with the following sage advice: Advice that I always remember when I'm getting into a panic and frustrated because something does not work and I can't find the answer in the manual.
Now a days for software packages and such I'm inclined to do as Mike says. Find then the documentation, give it a good scan over so you know where all the likely useful, relevant, parts are.Then get started with a quick start guide or such.
I was reading an article the other day that claimed that nobody read software documentation anymore, they get stuck, they do a google search, a lot of the time they find their question already answered on "Stack Overflow". http://stackoverflow.com/ I realized I had started to do that a lot as well, ending up in the same place.
I always try the thing first, then look at the manual later, but not because I am stuck.
From there, I start at it, whatever it is. As I explore, questions arise and I'll seek to answer those in a variety of ways. If a simple test can get me the data, I'll do that before reading docs.
There are kinds of documentation too, and perhaps this should be polled. Reference documentation, like an instruction set, or keyword list is something I won't generally read all the way through, however I will skim it and follow through on items of interest. Programming models, if present, are always something I read and think about.
There is narrative type documentation too! Theories of operation, how to, cook book, etc... I will typically read these all the way through because I'm looking for both technical data and some shared experience / insight people may have arrived at, or I'm looking for how people tend to think about it in general. Getting the right "mindset" is important to me because it tends to refine "best guess" type scenarios into more likely or plausible questions due to a somewhat more narrow field of inquiry these kinds of documents make possible. I particularly like those that include best practice info, not just the how and what details, but why and who too.
Finally there is "magic" type documentation. This is typically an expert treatment of some advanced use case or other related to the technology. Such documentation may range from a nice book to mere commented code. I not only read these, but read them again and again as insights pile up and I get it on a more basic level not having to think so much about it.
Three core types then:
1. Strict functional documentation. It's complete in terms of the information needed to use, but not expanded upon and there may not be enough context or narrative to carry me as a reader forward through the whole thing. Good for memory issues, quick references, etc... Not typically a read through. I do not find video / audio compelling, simply due to the non-sequental use case this type of documentation typically is associated with.
2. Practical. Cookbooks, how to, tutorials, theories of operation, etc... Generally I will read through, and nearly always when it's a get started type of thing. This type of documentation is easily performed with audio, video, interactive media as well as just the written word.
3. Magic! Advanced treatments whatever they are. Read many times, picking through them to get mastery. Video / audio can work here too.
There is a fourth, and that is the unorganized type of information found in a forum, or other gathering place frequented by other users of the technology I'm targeting. That is ongoing focus material in that it helps to get the mindset established for a deep dive, or it provides a frame of reference, context, etc... that might trigger insight that structured documentation might not, or it's serving as the basis for documentation that could exist, but doesn't yet.
StackOverflow has been mentioned. Yes! I will regularly Google for things too. A quick discussion can yield more than a sustained time reading documentation. IMHO, this is popular because people vary in their context and it's really difficult to make documentation that nails all use cases. Where that set of use cases is fairly structured, docs work well. Where that set isn't so structured, or assumes understanding from multiple disciplines, docs tend to work less.
I have had a little success using screen readers, but it's all kind of crappy with a significant computer requirement as well as prep to make things work, both of which somewhat marginalize the potential audio has.
On the few occasions where I've found a work or have been able to setup, I find this kind of documentation compelling. I can visualize things while not having to focus on reading whatever it is.
Potatohead, based on the length of your forum postings, I'm guessing you always write the manuals rather than read them.
Probably. :-)
I've never been one to "jump in" on something complicated, as that can pretty much backfire spectacularly:
I also don't cringe at long manuals, as usually they're in 5 different languages. If specifically irritating layout, I end up tearing/cutting out all the other languages to end up with a nice slim book. Then I start reading.
If it's a microchip, I don't know how one could not read its datasheet before connecting wires. Same thing with safety relays. I hate it when however the circuit diagrams are actually wrong, and wonder if the person making the wiring diagram read the rest of the manual.
stuff I've seen done:
Failing to install a driver before plugging a device in. (And the reverse, plug the device in THEN install driver). Only the manual knows.
Failing to read where to connect power, and thus inferring where not to connect it.
Spend hours and hours trying to communicate with something, where the manual specifically says it defaults to this address / baud / etc. Although for the life of my I can't understand why the pc software meant to communicate with that specific device isn't set to those defaults. (like address defaulted to 0 and 9600, even though every device the software talks to defaults to 2 and 19200, for example).
I've seen phone lines plugged into ethernet ports, I've seen USB cables plugged into ethernet ports. I've seen ethernet plugged into that crazy 8-pin RJ45 "nope it's actually serial" cable connector.
Pieces assembled in the wrong order, with no home for the last piece (a screw, a memory battery, internal jumper, etc).
I've seen heat or electrical isolation clearances not adhered to. "Too expensive to move everything around now!" Oh really, how about in 8 months you book that plane ticket because YOU'RE GOING to fix it. The funniest answer to that is is "okay". ???
Software package components installed in the wrong order, not as discussed in the installation readme.
Simple answer... I tend to dive in and look up later! :-)
Amanda
At the other end of the spectrum is the 3 page enclosure in 5 languages. :-)
Amanda
If it's hardware, then I read the datasheet cover to cover.
So yes, I read the documentation. The kind that I hate, though, is the ones that are written for users out of the 90's ("To create a new file, select File->New File. A New File dialog will appear. The first field is ... ". Ugh). That kind is usually denoted by "User Manual" or the like, and I skip it.
I should, and may start to read the beginning chapters of a manual. The intros just don't seem to make sense to me until I have delved in and have an idea of what is being talked about. In real life I usually jump in following a good short tutorial. Then I make a bunch of mistakes followed by a bunch of AHA'S! and then read further when I get stuck or ask for help. Guess I'm just a hands on learner. I learn (retain) best when I have a question that needs answered, or a problem that needs solved....
traVis.
And the grand daddy of all well-written Complete Idiot texts, "The Volkswagen Guide for the Complete Idiot" was my favorite "manual". It helped me to totally rebuild my '65 bug motor. It was a great read, going far beyond its instructional purposes. The writer details a story of how we maintained his car, while traveling the U.S. Whimsically written but full of how to's and instructions for keeping your VW running. I would read that text over and over just for fun!
Which makes a good point about well-written manuals. They should be informing and also interesting to read.
dgately
'Read' is a very broad term, - I certainly actively seek documentation and code examples ( which some may not consider Documentation, and some may )
However, how much I am able to read , depends on how well indexed and searchable, the docs are.
10's of MB of DOCs are useless, if you cannot actually find what you need.
I do.
If you are, then we're weird togther!
After that the rest of us can get on with asking questions on a forum which that first reader will answer as they are keen to show off their prowess to the world.
After that Google will find those already answered questions for us.
Now, this might seem as if we are all very stupid and lazy but I propose that it is makes very efficient use of human resources. That is we don't all have to waste our lives reading long, tedious, poorly written/translated manuals and try to understand them. We don't all have to learn a ton of stuff that we don't actually need to know to get our little job done. Further if the product turns out to be Smile, after much effort trying to use it, the first guy will let us know and we can move on quickly to something else.
Hmmm..I thought I was being humorous when I started this post. But I think I've convinced myself it is true. Witness the massive growth of StackOverflow and such like.
But some do feel the Bagagavita, the Bible, the Torah, and the Koran are manuals for living. One person's manual is another person's divinely inspired text, and so on. Many do tend to believe all the solutions are already in print.
We would then say "There is the problem..." because most of the manuals were WRONG.
Bean
That's why I put the smiley. Most people apply #2 and #3 to the "life" manuals. There's a lot of #1 and #4 going on too!
As for other documentation, I will often start off without a read unless mistakes or assumptions will be costly or dangerous, then the manual at least gets a review and any areas of concern are read through. Documentation should be written so that it is readable and that rarely happens anymore. I know cost is behind this and I have a feeling liability issues are behind it also.
Learning to communicate is a lifelong learning process. And so is writing well. Once can not afford to get smug and complacent.
For example electrical outlets have a specification for tightening the screws, where the wires are connected, to a specific tightness in "inch pounds". That is done with an "inch pound" torque screwdriver!
Back in the days when "books" were used for learning, for complex things, I would buy a couple of different books on the same subject written by different authors. One author might not explain something very well and the other author saying the same thing in different words would make it "click". (Of course these days you can search the internet for alternative instructions.)
And I think I am the only person who ever reads the owner's manual for a car! (I also buy the factory service manual and wiring diagrams and poke through that to learn how various things work.)
I also look up words in the dictionary for which I already know the definition. For example look up the word saloon.
I think he might be referring to the old nautical practice of storing dead people in barrels of rum on the high seas for transport back to Oregon. And the consequences of the predictable mix-ups that happened when returning back to port.
http://news.bbc.co.uk/2/hi/europe/4976754.stm
http://home.xnet.com/~warinner/nelson.html
But methinks I am a wee bit befuddled about the saloon thee be referring to now. Har-har-har!