Read The Fine Manual
Read The Fine Manual"Read the (F[a-z]*ing)? manual"
As the interthing changes our industry, plenty of projects grow to maturity (or not), and gain converts & followers WITHOUT a f---ing manual to read. When you get stuck, which do you reach for first, your fine manual, or Google?
For example, ExtremeProgramming started first on this wiki, and gained adopters well before its first manual. And, of course, publishers these days have trouble selling manuals of any kind, fine or otherwise, and many projects, such as RubyOnRails, constantly add new features, plugins, & patches with great abandon, documented only by their matching blog entries (of various levels of staleness).
So before you answer a newb's question with "RTFM" (and before you leave a dead trail in the archives to gum up searches), take care to check the manual has some hope of actually answering the question!
One might do well to reflect on why people do not RTFM, an area which rarely gets the attention it deserves. In fact, it turns out on further study that people (aka users) can go to extreme lengths to avoid using the online help (!) when this would be the logical thing to do. Instead they aimlessly flip back and forth between menus and dialogs looking for something to help them do what they want to do. Given the way many programs "structure" menu/dialog hierarchies, this can easily become a random process.
Expensively produced dead-tree-manuals by and large collect dust on the bookshelf of the resident "expert", and most users at a company haven't a clue where this might be.
Expensively produced manuals are often not worth the effort to pursue, since they have a poorly compiled or non-existent index, and the user can waste a lot of time trying to find answers to even very basic functionality questions.
Good manuals would focus more on UseCase or UserStory type approaches to describing program functionality. Rare indeed.
Writing manuals requires good manuals on manual writing. -- BoLeuf
In most GUI environments, like Windows, the interface is standardized, so you should be able to use most programs with little or no training. -- AnonymousDonor
What "Windows world" are you part of? I write programs for Microsoft Windows for a living, and I've found that things aren't nearly as standard as you'd like them to be. Often this is the fault of MicrosoftCorporation itself. For example, the Office programmers seem to be desperate to innovate. Every new release has some new feature. (Tabbed dialogs, the sliding icon menus that came with Outlook, and the new-style toolbars that came with Internet Explorer are just some examples.) I'm not trying to say there's no place for innovation, but it makes it frustrating to try to adhere to Microsoft's published standards when they don't do so themselves.
I think that there's a need for both UseCase manuals and reference manuals; they have different purposes.
But then again, I don't read manuals. I tend to throw myself into a product, and refer to the (online) manuals when I get stuck.
-- KatyMulvey
I agree totally about the need for different levels of documentation for different tasks. I do read manuals. For me with my user hat on, coming to a new and complex system, I want three types of manual:
Incidentally, I also want much the same three levels of documentation when coming to a new complex system as a developer! -- TrevorMendham
Nice work, Trevor. You just independently recapitulated some very expensive (so I was told in 1990) research Hewlett Packard did on what manuals should contain. There were actually five types of manual; one that's not in your list is Tutorial, and I forget the fifth. The presenters hammered home that no chapter should cross boundaries. A manual might contain separate Task Reference (type 2) and Overview (type 1) sections, but no chapter should try to be both a task reference and an overview. -- BetsyHanesPerry
I think a GoodManual? should be helpful for the user throughout the whole lifecycle of the system with separate sections for each phase:
To judge by the quick response turnaround here, the subject of RTFM is a sensitive one.
In an ideal world, I suppose context-sensitive online help might be adequate for most users. Recent times have also seen the implementation of context-sensitive buttons or ?-mode clicking to get specific popup help without going to another dialog. Of course, it can be predictably frustrating to ?-click on item after item to discover that almost no specific help has been implemented in a given dialog. When they are good, I most often stay with online help systems, but this is not frequent enough by far. Sadly the offline help can be just as bad.
Anyway, this has a certain connection with commented source, since there is a (tenuous?) flow of information from the programmer (and source) and development team, to the documentation responsible, to the online help designers.
Still, the point remains, that most users are extremely adverse to using documentation of any kind, even when it would seem to be the logical step.
On a sidetrack, I am amused by how MS will often bury interesting information in a readme textfile somewhere in the depths of some subdirectory under System along with hundreds of other files that the user is not expected to spelunk... -- BoLeuf
Years ago, pre-Windows 1980-83 command-line time frame, we developers made the same complaint about how people would refuse to read the one or two sentences we would put up on the screen telling them what key strokes or parameters or menu numbers to type in next. Not surprising, we developers were equally as bad as anyone else, even working programs written for us by friends. I conclude that these issues are all related, as Bo says, and has never gotten much attention from the psychologist researchers. Don't read the screen, don't read the manual, don't click the help. Even if the help did help, people wouldn't click on it nearly enough, and wouldn't read the paragraphs there. There is something interesting hidden under all this. -- AlistairCockburn
People want and expect the software to meet them more than halfway. Microsoft's "intelligent assistant" for Word bugs me, but the paradigm is right. People should be able to ask the software directly for help and also receive help unsolicited if the mechanism is not too irritating. In addition, it would be ideal if software actively learned and configured itself for its users.
I often think about the ramifications of voice driven user interfaces.. whether they will simplify user interface design and "on-line help" systems in general. Voice systems hold the promise of much less modality, but to be very effective they require context... the AI thing. The amount of work that is going concerning on in voice and lingual systems at MicrosoftCorporation's research arm [1] is striking. -- MichaelFeathers
See "How Help Files Don't" http://www.stant-1.demon.co.uk/help_not.htm Much online help is not very helpful. Meet the much maligned MS paperclip -- which can often be more helpful by being gone.
Windows-style help always irritates me, because it only tells you what the product can do, not how to achieve what you want to. And so many times, it turns out that the answer is "this program can't do that". I tried reading help many times, I learned that random clicking produces better results. -- JohnFarrell
Assume you are working with your typical Windows program, and you think you need to use the XYZ-feature, which you haven't used before. You know you can switch it on with a checkbox in preferences, but you don't know if it really does what you think it does.
In my experience...
Speaking of the "find that one checkbox" config problem - am I the only one who, when faced with a cyclopean horror of a tools->options dialogue (complete with other dialogues launched by variations on "advanced"), keeps wishing that there was a ctrl-F-style functionality available? -- MartinZarate
Often I'm looking at a screen with a checkbox with a label saying "Flizzbot". So I press the "Help" button, and receive a fine screen that tells me that if I click on this checkbox it will "enable the Flizzbot option". Great; so they couldn't do anything more than read the screen to me. (I don't blame the people writing the technical documentation; often, no one will tell them what the option does.)
[Blame the company instead. Actually, blame the industry. That's probably more accurate.]
No. We all have to take responsibility for the work we produce and the level of completeness of the UI. Who among us wants our product gloriously listed on "Interfaces That Suck Out Loud" for the third straight season? Don't go blaming anybody else for your crappy work. If it needs user help support then insist that such support is included in the product. If your boss/client/whatever insists that the product go out without this kind of built-in help then tell them loudly and at regular intervals that this is how crap products are made, and you wouldn't want to buy such crap yer own bad sef.
A Wiki extension could be written to allow a help key to open the page HelpXxxxx?, where Xxxxx is the current page name. A default of HelpHelp? is called if no help is provided. This provides online context sensitive help in a Wiki. Then RTFM becomes WTFM in true Wiki style. -- DaveBerkeley
Dogbert's tech support: "While you hold, read the free novel we've enclosed. It's a Spanish story, about a guy named 'Manual'."
My personal favorite manual is ThePerlCookbook. It is both a quick-and-dirty resource for "How do I get this done?"-type questions, and a resource for people wanting to dig further into the nooks and crannies of the language. It's not authoritative or exhaustive, though; for that you'd want something like ProgrammingPerl.
EditText of this page
(last edited July 16, 2013)
or FindPage with title or text search