Please Kill RTFM!
When “Read the F$!%ing Manual” Veils Bad Design…
I’ve seen it time and again in my field of work when someone asks a question that’s considered trivial, devs say it, sysadmins say it, DevOps say it:
“Just RTFM man!”
RTFM (Read The Fucking Manual) epitomizes the nerd who hates people. It stinks because it is condescending. And it assumes that anyone who doesn’t peruse the manual is either stupid or lazy.
Don’t get me wrong. This post is not about condemning documentation or dissuading people from reading it. Good documentation is exceedingly important and I am the first to complain when it doesn’t exist.
I am also not extolling lazy people and advocating to spoonfeed them when resources are abundantly available to them.
No, this is not what this post is about.
This post is about anyone who uses documentation as an escape from good design. It is for those who create overcomplicated tools that are awful to use and then belittle their users by telling them to RTFM.
Let’s talk about Stupid Designs, not Stupid Users
In his phenomenal book “The Design of Every Day Things”, Don Norman makes an excellent point on chapter five:
We must learn to see human errors as design problems and not human incompentence.
And yet it is so common to continuously attribute errors to human stupidity and not the software they operate, or as the joke goes:
But if the ultimate aim of good design is to be approachable and intuitive, why do we keep making tools that require reading long manuals to find your way around?
An inordinately long manual is a red flag for bad design
Imagine if I made a toaster where you had to press twenty buttons in a weird order for it to toast bread or it stabs you. Hence, the only way to operate this toaster is by reading a very long document outlining every step in order.
So I start writing the manual of my wonderful invention and I feel so pleased with myself. “I am so good at writing documentation, my users will be overjoyed reading it, they will certainly see how smart I am. Except for those who don’t — they are idiots.”
Now imagine I am so daft that while I am writing this big set of instructions not once it goes through my head. “Wow, this process maybe is too convoluted, perhaps I should design a better toaster”
It seems rather ludicruous, but is it? Take a look at this video of a real product “manual”:
It is also common with DevOps tools I’ve used in the past. Unnecesarily long and tedious documentation is generally the best indicator on whether a product is well designed or not.
Yes, this applies to complex systems too!
I am not being facetious here. I know that complex tools require lots of documentation. I would not expect an airplane manual to be a single page that says: “Go up fast, come down easy”
But even complex tools don’t need to be unncessarily difficult. Just because you are creating a tool that is complex, it doesn’t mean that it needs to be an incoherent large stack of features and functionality without a cohesive design around it.
If reading the manual is the only way for you to understand every functionality of your application, you have failed at design. In fact, I would argue that complex systems require a lot more thought and effort at designing them to achieve simplicity and ease of use, and you should never assume that because it is complex and used by “experts” you don’t need to care about designing it.
Let’s look at another disingineous meme for a good example:
Anyone who has been tasked with running, automating and maintaining complex systems knows the pain of having an issue and absolutely no clue what’s causing it, and I can assure you that it is very rare when five minutes or two hours of reading documentation will solve it.
In this case a comprehensive manual for the complex system may help, but if you don’t know what you are looking for, it very likely won’t. Instead, well designed, complex systems produce helpful feedback in the form of contextual error outputs that tell you how to fix the issue or point you where to look for a solution in the manual.
Conclusion: Developers need to strive to be better designers
Good design equals excellent communication, better than documentation, blog posts, videos or any other way you use to teach and sell your product and developers should aim to learn UX princicples to do this better.
It is always harder to create good designs, but it isn’t that hard to understand what good design is. The book “Design of Everyday Things” boils down good design to two points:
Discoverability — Is it possible for users to figure out what the possible actions are to use your tool?
Understandability — Is it possible for your users to figure out how the product can be used, is the language clear enough?
If you can achieve both goals above without leaning heavily on documentation you have succeeded admirably.
Read my next post for more specific design principles you can use to make an internal developer platform a joy to use…
If you feel compelled to kindly give praise, remember you can hold down the clap button to lazily express your enthusiasm 😉
