Posted by m.jackson on 27 March 2012 - 5:29pm

One of these four exchanges occurs regularly in everyday life…

Tourist: “I think I'm lost, please could you tell me how to get to the National Portrait Gallery?”

Policeman: “Read the f------ map!”

Diner: “Excuse me, what are today's specials?”

Waitress: “Read the f------ menu!”

Interviewer: “And, minister, what is your policy on unemployment?”

Politician: “Read the f------ manifesto!”

Researcher: “How do I convert my model into a PDF as it doesn’t seem to work?”

Developer: “Read the f------ manual!”

Yes, it’s number 4, a response so popular it has its own abbreviation – RTFM – and a Wikipedia entry!

Maybe this is because in the e-world, interacting at the far end of a network connection, denied a face-to-face encounter, it’s okay not to be civil. Given the volume of witless, gutless, loveless, artless, malicious, inevitably-anonymous rantings that any “Comment on this news item/post/video/image” request invites, this seems to the case. But this is a sorry state of affairs for software developers and in this article I’ll argue why, with the help of kindred spirits of the virtual world that Google helpfully revealed to me.

Why tell a user to RTFM?

Why is RTFM considered an appropriate reply to a cry for help?

Well, RTFM is a great way to release your frustrations at those users who don’t take the time to read the manual and waste your time by asking for help. But, RTFM also saves you time as you don't have to explain to these users either the solutions to their problems, or where they can find the solutions. As a consequence, RTFM has become accepted as a valid response in what has been termed the teach-yourself culture of open-source projects, which is a consequence of the limited financial and human resources available to these projects (see RTFM! Teach-Yourself Culture in Open Source Software Projects by M. T. Schäfer and P Kranzlmüller).

RTFM also provides a great way to avoid addressing issues with your documentation and thereby to avoid taking responsibility to fix these. It liberates you from boring activities like support and writing documentation and frees up your time to spend on the fun, interesting and only worthwhile task there is...coding!

Why you should never tell any user to RTFM

So, there are some (believed) benefits to RTFM, but let’s lift up the stone and see what darkness lurks beneath…

Well, for a start, it's rude, it’s swearing at a stranger. Although it’s an acronym the intent is still there. As a result, it's "not professional in the least”.

Your rudeness, in turn, can make you sound like an embittered, arrogant, aggressive elitist. Andy Lester comments that RTFM is “used as a reply to a question that the geek thinks should not have been asked…it’s as if the rude geek is saying 'The information exists in at least one place that I know of, and therefore you should know that information, too." Jack  Wallen, who did RTFM with little success, comments that “if you are ever looking for help with … open source, and you hear the phrase RTFM, know that most likely that is either someone too lazy to type or help or someone wanting to make sure you understand exactly what kind of help you are looking for before you look.” Software developers have enough of an image problem without voluntarily conforming to their worst stereotypes! Even worse, someone may follow you with a helpful response. As highlighted on the SQLskills.com blog “…a helpful person will come along and add a good response with some helpful links and advice…and the 'RTFM' guy ends up looking like a bit of a plonker!”

Not only can RTFM reflect badly on you, its taint can spread to your organisation or community. Consider this comment on the SQLskills.com blog “RTFM – the standard reply you get in [name deleted to save blushes] forums. Do we really want to turn like that?” It can be especially damaging to the image of open source projects as it contradicts the (alleged) community-mindedness of such projects (as opposed to the secretive evil world of proprietary corporations). Jack Wallen comments that “RTFM” is “…almost a battle cry for the open-source community.” Grumpy Nerd, in a blog post titled “I Hate Open Source Software – Why Open Source Sucks” argued “...I'm supposed to bet my job on the trouble ticket turnaround time of the four crusty nerds hanging out on Source Forge who are going to tell me to RTFM” (before adding “to which there is no f------ manual because no one got around to writing one.”).

So, RTFM may cause you, your project, your organisation and your community to lose face, but it still saves time, right? Er, no, it’s not much quicker than a polite response. A poster on the SQLskills.com blog comments “I always giggle when someone posts a 'RTFM' type response when it would have been quicker to have just answered the question.” Indeed, helping a user to find information now may save you from requests for help from the same user in the future.

If that wasn't enough, RTFM also assumes that a user has not already read the manual. While some people do cry for help at the first sign of trouble, for many others it’s an absolute last resort. Jack Wallen’s blog post, aptly titled “RTFM: I did, and it didn’t help” lists his battles with a manual. A succession of battles with a poor manual may make a user more inclined to ask for help as a first resort. Without further information, how do you know?

RTFM can also deter others from asking for help. Consider a new user who is looking for help, who searches fruitlessly, considers emailing for help, checks out the email archive first, then sees “RTFM…RTFM…RTFM” and decides to keep quiet. It may, in consequence, deter them from using your software in preference to those with similar functionality but more supportive communities.

Maybe the user can’t find your manual

Maybe the user can’t find the manual because your software distribution or release is poorly designed? As a comment on the SQLskills.com blog puts it, “TFM is not always easy to read or find.” A common response to this is “use Google” but if the only way a user can find out more about your software is via Google, what does that say about the ease of use and navigability of your website? It's a problem that needs sorted, is what it says!

Instead of jumping in with “RTFM” consider whether your manual (or FAQ or tutorial or whatever) is readily accessible. Yes, you know where it is but it’s your software, what about a new user? Repeated requests for help may indicate that users are having problems finding your manual and until you ask them, you’ll never know.

Maybe your manual could be improved

Maybe your manual is poorly designed, incomplete or unclear. How do you know? Have you ever used it yourself? Perhaps not, since you wrote your software so you don’t need it. Open-source software, in particular, has been hammered for the quality of its documentation. Consider, again, Grumpy Nerd, “Writing documentation sucks. Which is why most open source software is buggy and features little to no documentation making it useless to everyone outside of the authors.” Or Design by Fire who comments, in a post entitled “I would RTFM if there was an FM to FR”, that “documentation for OpenSource technology is truly horrendous…Until… addressed, the OpenSource movement will be nothing more than an underground clique for those who have nothing better to do with their lives than memorize massive amounts of obscure command line syntax and drink lots of Red Bull.” Jack  Wallen documents his battles with a particular open-source product and its documentation and rightly concludes that, in such situations, users may have no other option but to ask for help, “in the open source community the FM is the community in most instances. And when we reach out for help we ARE RingTFingM.”

What it does, how it does it and how to use it

Sometimes manuals do not give the users the information that they need to use the software. Manuals often focus on what the software does, with exhaustive lists of command-line options and parameters. Research software often points users to a paper that describes how the software works, understandable since the code embodies the research novelty. Unfortunately, telling a user what the software does and how it works is not the same as telling them how to use it, no more than telling a person what a car does and how the engine works helps them drive it. This was Jack Wallen’s experience, “I had never come across an 'FM' that was so lacking in the actual 'how to' area.”.

Users deviate from the documentation

Carroll et al. in research into minimal manuals observed that users, especially new users, frequently deviate from step-by-step rote following of the documentation with “episodes of self-initiated problem solving”. Such behaviours were motivated by the underlying motivation of the users to start using the software to address their problems and achieve their goals as soon as possible. They quote one user who commented “I want to do something, not learn how to do everything.” Despite dating from the mid-80s Carroll et al.'s observations make for interesting reading:

• The minimal manual by Carroll, J.M, Smith-Kerker, P.L., Ford, J.R. and Mazur-Rimetz, S.A..
• Learning to use word processors: Problems and prospects by Mack, R. L., Lewis, C. H., and Carroll, J. M.

Different types of users have different needs

Sometimes manuals do give users the information they need but fail to take into account different classes of users. These could include, depending upon the software,

• Users who use the software as-is and do not write any code.
• Users who use the software as-is but write code. For example, developing plug-ins for component-based software, or clients for server-based applications.
• Users who both use the software and may want to customise it to fix bugs, extend its functionality, improve its scalability, robustness and performance, or whatever.

As a result, the documentation needs to be structured so that each class of user can find the information suitable for them, whilst not exposing them to information that is not suitable. For example, a user using the software as-is needn't be exposed to information about what APIs are available or setting up a development environment.

As an example, the OGSA-DAI distributed data management software can be deployed to expose databases as web services or RESTful endpoints, without the need to write any code: it provides a Java client toolkit to allow the development of clients that use these endpoints to access the data; it provides server APIs allowing components to be written to implement data transformation functionality; and it’s open source, so the OGSA-DAI framework itself can be modified. Each of these classes of user – deployer, client user, client developer, server developer, framework developer – has specific tasks they want to do and these require specific types of knowledge. As a consequence, the user documentation is partitioned into sections for each of these user classes.

Incorrect and inconsistent information

Sometimes a manual may be incorrect or inconsistent. This can arise when, for example, the software is changed but the manual is not updated to reflect those changes (since writing documentation is less exciting than coding, remember!). Similarly, confusion can occur for online documentation if it is not clear which version of the software applies to the documentation. Inaccurate documentation can be more problematic and time-consuming for a user than no documentation at all.

Imprecise information

I’ve lost count of the number of times that I’ve read manuals which say “now edit the connection configuration file”, “use the query class” or “now run the application on the inputs”. I then have to rake through the software or the documentation to find the location of the connection configuration file, the full Java package and class name of the query class or exactly what command-line invocation is needed to run the application. It's even more frustrating if I know that the developer who wrote the documentation knew the information, but couldn’t be bothered taking the time to share it with users like me!

WABM?

Instead of jumping in with “RTFM” think about whether you need to WABM (“write a better manual”). Don’t treat manuals as an afterthought but as an integral part of your software, deserving of just as much time, care and attention in terms of design, authoring and - yes - testing, as well as ongoing improvement and refactoring as your code!

For advice on writing user documentation see:

• Usability guru Bruce Tognazzini’s How to Publish a Great User Manual
• UserFocus, Tips for writing user manuals

Maybe your software could be improved

Maybe the problem is not with the manual but with the software! Making your software easier to use could reduce a user's reliance on your documentation and reduce the risk of them having to ask for help. It may also make it easier to write your documentation – a common assertion is that the more usable the software, the easier it is to describe and explain.

Usability guru Jakob Nielsen lists heuristics for the design of usable software. These apply not just to GUIs but to command-line tools too. One heuristic is “Help users recognize, diagnose, and recover from errors”. Now, the following would help a user recognise an error,

$ load configFile.xml Error

But this provides no help for diagnosis or recovery. If the documentation was similarly opaque, the user would then head for their fave search engine or start to draft their email. Now consider:

$ load configFile.xml XML parsing error at line 4 character 2 in configFile.xml. Unknown element: databaseUL. Legal elements include: databaseURL, databaseUserName, databasePassword.

The user is not only informed that there is an error, but why the error occurred and where it originates from.

Malcolm Barclay comments that “RTFM is no excuse for not having a well thought out, coded & polished design with good usability placed squarely in the centre.”

But what about users who cry “help” as the first, not last, resort?

You will always get someone who cries for help at every hitch. Asking for more information can identify these individuals. Maybe they’ve never been trained to search for help. By providing a link to a FAQ or the relevant part of the user documentation, you may help them to find information themselves in future. Likewise, asking specific questions about their question (e.g. what version are you using, what operating system, what database etc.) may promote the asking of more appropriate questions in future.

Users who really are not willing to help themselves, or help you to help them, are easily recognisable…typically they’ll just send the same question over and over without giving you any more information. But, still politeness can save the day, a kind email “we can’t help you if you can’t help us”, “really, we insist”, “I’m sorry but if you send that message again we’ll have to sadly conclude you’re a spammer and unsubscribe you” can do wonders, without a loss of face on the part of yourself, your project and your community.

Suggestions for a more civil software world

So, to summarise with some top tips,

• Be inquisitive. Maybe the user has read the manual…you can’t know until you’ve asked. Jeff Lunt comments, “Ask why – first and foremost you need to understand why the user is having a problem with your application, then you need to correct the flaw that is causing the problem in the first place, thereby eliminating the need for the user to ask the question at all.”
• It’s not just your image. When you interact with your users, you are not just representing yourself but your project, organisation and community, and users will judge the whole based upon its parts.
• View requests for help as opportunities for self-improvement. Instead of replying with RTFM, consider whether you need to Rewrite The Flawed Manual. Read up on user experiences and what makes good, and bad, documentation and help. Or consider whether you could rewrite your software to make it more usable.
• Iterative development works for manuals too. Don’t treat manuals as an afterthought but as an integral part of your software, deserving of just as much ongoing improvement and refactoring as your code!
• Civility costs nothing. While writing documentation is difficult and time consuming, civility is easy and cheap. Say RTFM verbally, to your screen (indeed revel in the liberty of being able to say far, far worse – this works for me, blush!), and, tensions relieved, compose a polite response, even if it’s just a URL to the appropriate place in the manual. And, if you can’t say something civil, say nothing. Check out the Ubuntu Forums Code of Conduct for guidelines on helpful, civil responses to users.
• Your new users today may be your champions and collaborations tomorrow!

And finally, XCD’s cartoon on RTFM.