How to RTFM – Tips for a life of discovery
22 Nov 2011 – Houston
My friends and I have often discussed the topic of programmer education. The idea is that programming is somehow unapproachable or favors a certain rare learning style. I can sympathize with this perspective. At the same time I feel that learning how to approach the unapproachable is somehow at the core of becoming a good programmer. The name of this all-important technique is RTFM.
Update: RTFM T-Shirts now available. Spread the euphoria!
Everyone was a newb at some point. Chances are some jerk in
#latest-fp-languagetold you to RTFM and that rubbed you the wrong way.Well, I’m here to tell you that RTFM is like “Amen!” (or “So say we all!” for you BSG fans) for programmers. These kind souls are just trying to remind you of your commitment to reading TFM which should be no less than religious.
Why RTFM?
First, I really recommend reading Vivek Haldar’s article comparing GUIs and CLIs. This is soul food for the aspiring reader of TFM. Internalization is critical for programming. It’s the only thing that separates effective from ineffective programmers. Your goal is to get as much of your daily required knowledge into your brain-RAM as possible. You do not want the syntax of your language of choice or the switches to
grepto reside on disk or on the network somewhere.RTFM forces you to think about what you’re trying to do, and understand the tool you’re using to do it. It also allows you to discover other tasks that the tool might help you with. It is my experience that this extra processing forces one to actually, uh, think?
The Rules of RTFM
These are simple rules that should guide your daily RTFM practice. The goal here is not to simply get things done—we want to get things done and have learned (internalized) new techniques that will help us next time.
Rule #1: Do not Google (or DuckDuckGo) first
Google is a great tool. Google will match you with the guy who had your problem and show you exactly how he solved it. However, Google Is Not Your Friend.
The reason is this: once you’ve found the one-liner that will get you going and you’ve copy-pasted it into zsh, you’re done. That’s it. Google has deprived you of your quality time with TFM.
Using a pure RTFM strategy, the voyage of self-discovery is something like:
- Think about what you’re trying to do or why you’re getting that error.
- Remember a similar tool or experience you’ve used before.
- Read TFM for that tool or related tools.
- Discover new techniques or ways to apply your tools.
Google is the deus ex machina of the programming world, punching plot holes in your epic rise to RTFM stardom. Google has weakened your ability to solve problems by jumping straight to discovery. If you absolutely have to Google, then make sure you also take time to understand the results of your Googling and how you might have found the answers through a more organic process.
Rule #2: Do not settle for an example
When people say that humans learn best by example, they really mean that humans avoid learning when they have examples. This is because examples enable one to employ tools without really understanding how they work.
Try to avoid learning things in opaque chunks. If you’re working with the shell, make sure you’re learning what the
a,u, andxswitches do inps aux. This meansman psfollowed by tinkering with the various options until you develop a satisfying freedom of movement along the various axes of the command.If you’re working from a big section of code, try changing it and seeing what happens. Make sure you can account for each part of the code. Seeing a chunk of code as an indivisible unit is buying a season pass to that same old article on Stack Overflow for the magical incantations.
Rule #3: Sometimes the code is TFM
Not all projects have great documentation. That being said, most of the projects I use have docs in the decent to awesome range. For example, I would consider Android docs better than decent. I’d consider the FreeBSD handbook to be awesome. Most of the programming languages I use are very well-documented.
Hopefully the documentation for your project captures all behavior that is intended to be public. That still leaves a couple of reasons why the code itself may be the best or only documentation for a piece of software.
It’s my guess that writers read much more than they write and filmmakers watch many more hours of film than they produce. A programmer has to read code well especially now that most programming work consists of correctly using libraries and services written by others. In any case, code reading is sometimes the only way to figure out what received software does and how efficiently it does it. Don’t have the code? Try replacing that component with one of these.
Rule #4: Question your questions
It’s a little-known fact that TFM will answer any question you pose it—as long as it’s the one that TFM was written to answer. It’s like one of those movie kung fu teachers. You’re going to be chasing the chicken and waxing on and off until you
man -kup and start asking the right questions.This generally requires knowledge that won’t be cited, linked, or in any way communicated by TFM. You’re not going to understand a language spec without understanding what the heap and the stack are. Insensitivity to the strangeness of one’s questions is the most difficult obstacle to overcome in RTFMing, and it’s also the most likely to be solved by contact with another human being.
Still, resist the urge to talk with someone. If you need some release, open a shell and
echointo/dev/nullor tell your barber. After much confusion, much RTFMing and some good luck your brain will turn inside-out and you’ll have an epiphany.Maybe.
Although artists often learn by copying other artists, we programmers are often in the rather fortunate position of having manuals available. This article explains why we should RTFM and [imho] it should be required reading.
