If you want them to RTFM, write a better FM

If you want users to RTFM, write a better FM

on May 6, 10 • by Helen Abbott • with 9 Comments

When I was documenting a new refactoring plugin for Vim, I checked out the Vim web site, and came across this blasphemy: Vim isn’t an editor designed to hold its users’ hands. It is a tool, the use of which must be learned. Later, someone sent me this beauty, from Elitist Jerks: Stop being lazy [&hellip...

Home » Documentation » If you want users to RTFM, write a better FM

When I was documenting a new refactoring plugin for Vim, I checked out the Vim web site, and came across this blasphemy:

Vim isn’t an editor designed to hold its users’ hands. It is a tool, the use of which must be learned.

Later, someone sent me this beauty, from Elitist Jerks:

Stop being lazy and read.

Are users lazy? Do they expect hand-holding? Do they expect one button and no manual?

Or is this more true to life?

If you want them to RTFM, write a better FM

In the end, it probably comes down to this: Make tools usable. Then technical communicators can spend more time creating truly helpful help, and less time explaining a bad UI.

If our goal as communicators is not just great help, but a great product, Agile makes more sense than ever.  If we want our usability suggestions to be implemented, we need to get developers’ attention while they’re working on that feature. Find the rough edges that would require a lot of splainy-splainy, request a change, and then rejoice that we don’t need to explain what’s now obvious. Sometimes it’s hard for me to decide what’s a rough edge. Would my audience of developers find this as confusing as I do? But I’m learning to trust my gut.

At the same time, though I appreciate the benefits of Agile, I’ve started to worry less about the help being “done” at the end of an iteration; instead, I want to make sure I understand a feature well enough before the end of the iteration to suggest design changes and know what help will be required.

Related Posts

9 Responses to If you want users to RTFM, write a better FM

  1. doomleika says:

    well, I would object that vim has rather above average manual.

    Still, from a practical stand point, if anyone has problem with manual, that means the manual is not good enough.

  2. chris says:

    I agree, if there is no manual, then you can’t read it.

  3. Helen Abbott says:

    Mark: I asked my blog guy why, why, why, and he just mumbled something about different browsers. I will not rest until this question is answered.

    Chris: I read your whole comment. Twice. (Then again, I’m a writer.) Yep, one of the biggest problems is handling a diverse audience. Thanks for the pointer to RogueWave – I’m always looking for examples of good help to learn from, so I’m now reading their stuff. Loved the image of the seniors turning their PCs on and off for an hour. Reminded me of the time I was on the phone with my mom trying to explain how to enter a URL in a browser.

  4. Chris Chiesa says:

    Well! It’s ABOUT TIME somebody in (by my standards) a position to be HEARD noticed this situation and SAID SOMETHING.

    I’ve been programming professionaly for 22 years now, and programmed for fun for eight years before that, and the vast majority of developer documentation I’ve seen has been completely abominable. Unix manpages and Windows (e.g. MFC) developer help both are a stench in my nostrils, mainly because they make arrogant presumptions about whom is their audience. First there’s the Unix tradition of using ordinary words, in lowercase, as function and command names. The manpages invariably use them in sentences without setting them forth with any kind of punctuation, which can make for a stuttering, stumbling reading experience, especially to the newbie who DOESN’T KNOW that certain words are “well known” command or function names. MFC help borrows heavily from that ugly tradition and compounds the problem by assuming that the programmer has come up through the ranks of Windows programming from the beginning. I myself came up through VAX/VMS, got spoiled by Digital’s crystal-clear, thoroughly complete documentation, and found both Unix and Windows to be complete nightmares to get started with. I distinctly remember spending about a month fooling around with MFC and being thoroughly confused before I got the key point that a “window,” a “window handle,” and a “CWnd” object were NOT THE SAME THING. You’d think such a fundamental concept would be mentioned somewhere early on, but no; you had to have been a Windows programmer from way back, to know that, coming in.

    On Solaris there were various third-party packages whose documentation quality varied widely. There was a package called Ice that I would have to describe as an OO/marshalling wrapper around RPC, but whose documentation consisted SOLELY of a long, dragged-out partial explanation of how to write one particular program using it. There was NOTHING about the overall concepts, general principles, or how to infer what was left unsaid or extrapolate Ice’s use in building other kinds of programs. There was no reference manual. Other people in my group eventually were able to build useful software with Ice — but I myself was never able to get through this so-called documentation. Conversely, we also used RogueWave tools, and THEIR documentation was BEAUTIFUL. You didn’t have to have much of any prior knowledge, either of the RogueWave world OR of C++ templates (which were used heavily in the toolkit) to quickly get up-and-going with it.

    Speaking of templates, is there any “thorough” documentation of STL? All I’ve seen (though I admit not looking very hard) has been the O’Reilly “STL Pocket Reference” (I have it here right now) which, frankly, is relatively hideous. It’s organized funny, the descriptions are so terse as to be more confusing than enlightening, and it’s not clear — for one example — which container-class-method descriptions apply to which containers. I can easily spend an hour or two trying to get e.g. the generic “find” algorithm to work, and at this very moment have had to “not implement” a Remove method on a class whose internal implementation is unfortunate enough to be a Vector, because I haven’t been able to find a way to remove an element from anywhere but the head or tail of a Vector. Maybe it can’t be done and I’m wasting my time — my whole point is that I CAN’T TELL.

    I could go on and on about good and bad documentation I’ve encountered, but I THOROUGHLY AND HEARTILY AGREE that there is tremendous room for improvement in the world of documentation.

    (On the other hand, having tried to teach complete, utter, absolutely ignorant-and-technophobic newbies the rudiments of using a PC, I can tell you that it is impossible to cover EVERYTHING in enough detail and depth for EVERYBODY. My mother, for example, attended a senior-citizens’ computer-usage class in which they spent an hour just learning how to turn the computer off and on. I myself found that I had to start her education with a careful explanation of how the mouse, on the desktop, corresponded to a pointer, on the screen, and that “moving the mouse AWAY from you makes the pointer go UP,” and so forth. There’s no limit to the amount of handholding that some people will require, and it is necessary and meaningful to ask, “where do we draw the line?”

    Too, more generally I’ve observed that a lot of people won’t spend the time to read something that’s too verbose or complex (how many of you are still reading THIS?), so any explanation has to be kept simple and as a direct consequence must be largely incomplete. Organizing a manual hierarchically might work but would be a logistical nightmare to produce and maintain, not to mention you’d have to have a section up front explaining the book’s organization to the reader. Still, if you could find a way to manage it and it became a standard (like the traditional layouts of dictionaries, encyclopedias, man *cough* pages, etc., it might be a good thing in the long run…)

  5. Doug Holton says:

    Better yet are tools that need no manual – they have contextualized help built in.
    When’s the last time you read a manual for a game, or for virtually any software you use.
    Even programming shells/REPLs usually have enough built-in help to use.

  6. Off-topic, but why such small fonts? Why? Why? Why?

  7. flink says:

    Vim? For real documentation? Vim is targeted as developer’s tool. That’s why they feel that the user must learn the tool. IMHO, a user having VIM as their primary editor should have an intimate knowledge of the tool’s interface. Otherwise, they may as well be using notepad or pico.

    VIM, Eclipse and the other heavy-weight development environment editors make available a great deal of functionality, but to make any use of it, you need to know the keyboard shortcuts and know how the features all work.

    This is similar to knowing how to drive FrameMaker, RoboHelp, or Flare. Sure, you can type in the text you need and manually format everything, but if you know how to create and use styles and other features of those tools, then your productivity is greatly enhanced.

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top