Sep 28, 2022
Min Read

The Clash Between RTFM Culture and Developer Experience

Jean Yang
Share This Article

In the last decade, we’ve seen a lot of innovation in mainstream developer tools. We’ve also seen a lot of innovation in developer experience–for instance, for frontend development platforms like Vercel and APIs like Stripe.

It’s not controversial to say that we haven’t seen the same kind of developer experience improvements for backend and infra tools. My hypothesis on why? RTFM culture.

RTFM, short for “read the f’ing manual,” became the cultural norm when a small number of programmers were maintaining software largely for free. Since then, software development has become democratized. Developer tooling has become commercialized. Software has outgrown RTFM culture, but developer tools haven’t let go of the RTFM mentality.

My Tweet about the realization that led to this blog post.

In this blog post, I’ll talk about where RTFM culture came from, how I came to realize that RTFM culture lurks in developer tools today, and how “hardcore” dev tools could do well to outgrow RFTM culture and embrace a more user-focused, service-oriented attitude.

How Software Outgrew RTFM

As someone who learned to program in the early 90s, I came of age in RTFM culture. Software was DIY and use-at-your-own risk. You could build whatever you wanted, as long as you could figure out how to do it. You could build without the responsibility of bringing other people along.

While I acknowledge the phrase “RTFM” is undeniably aggressive, the mentality is not all bad. It’s reasonable to protect the time of software creators, especially if they’re not getting paid. It’s not terrible to expect someone to consult the documentation before asking questions, especially to overloaded maintainers.

But there’s a time and a place for everything. Software is no longer some wild experiment: it now runs most of our lives. Software powers our phones, our homes, our cars. Apps influence the structures of our social and professional networks. Software bugs prevent us from making doctors’ appointments and getting insurance payouts. We entrust a larger number of developers than ever before to build reliable and trustworthy software.

Given the importance of training up software developers, RTFM culture no longer makes sense. We as an industry have met the demand for software development by adopting more accessible tooling and growing the pool of developer talent, a population that is set to exceed that of Canada by 2030. This has fueled the rise of commercial developer tools, especially software-as-a-service tools. The incentives align for doing away with RTFM: everyone wins developers can quickly adopt new tools quickly.

How I realized RTFM is still a problem

Until recently, I believed that RTFM culture was dead in SaaS. Until it became my goal to deeply understand all of the potential issues with our Akita app’s user onboarding.

As the creator of a developer tool, I recently reached the stage where it came time to make our user onboarding experience more accessible. I started reaching out to users who did not finish onboarding and, at first, I was not surprised: few users wrote back. They simply must not be that interested in our product, I thought.

Then we got more metrics and I made a surprising discovery: if I wrote a user acknowledging specific frictions I thought they might have encountered, I often got an answer—and was often able to get that user successfully set up with our product.

People weren’t dropping out of our product because of lack of interest. But why weren’t they writing back unless I wrote to them in a specific way?

I could have written this off as user attention span issues, or the common marketing wisdom that nobody writes back unless you spam them. But as I did more of these communications, I formed a hypothesis: users would often assume it’s on them to figure out what’s wrong before getting back to us. These users had internalized RTFM—and were reading the f’ing manual. But, since they were busy and manuals take a long time to read, they were simply disappearing.

I then tested my “internalized RTFM is causing users to disappear” hypothesis. I started explicitly telling users it’s on us to help them—and meeting them where they were by reading their logs to see where they got stuck. The continued uptick in responses gave me confidence in my theory that users disappear when they think it’s on them to understand what was wrong. This led me to a couple of realizations:

  • There’s internalized RTFM in users. With developer tools, it remains the norm that users expect to do the work. We found that we needed to go beyond the usual “don’t hesitate to ask questions” to make users feel comfortable engaging with us.
  • There’s implicit RTFM in products. The discovery of internalized RTFM in our users led me to reflect on what we were doing to encourage this behavior in our users. I realized that even though our language was friendly, we would sometimes expect the user to read or understand quite a lot. I don’t think we are alone in this.

How RTFM gets in the way of developer experience

My experience with our own users led me to realize that many developers (including developer tools creators!) believe, to some degree, the following about developer tools:

  • If a user doesn’t understand what’s going on, it’s on them rather than the tool creator to put in more work.
  • One should take pride in understanding the intricate workings of technical tools.
  • Many technical things are just hard to explain.

Many go one step further to believe that tool developers need to have their time protected:

A valid point that does not apply to commercial developer tools.

For noncommercial tools with small numbers of maintainers, these sentiments make a lot of sense. But we’ve made a lot of inroads in developer experience these last few decades—and people are often paying lots of money for these tools! Just like a customer shouldn’t expect a cafeteria to have the same level of service as a fancy restaurant, people should expect to get the service level they pay for in developer tools.

But before I talk about how we can shift towards a “the customer is always right” perspective for backend-heavy developer tools, I should acknowledge a core reason why frontend and API tools have had an easier time with developer experience. As I’ve mentioned in a previous blog post, tools like Vercel and Stripe are abstraction tools that automate away well-defined pieces of functionality. Many more backend-heavy tools, for instance tools in the monitoring and observability space, are complexity-embracing tools that exist to expose the inner workings of technical systems. These tools inevitably deal in a lot more technical detail. But that’s not a reason to expect users to meet the tool where the tool is.

Here’s what I believe is necessary to shift away from implicit RTFM-attitude in complexity-embracing tools:

  • If a user doesn’t understand what’s going on, it’s on the tool creator/service provider to figure out the right abstractions to provide a better experience.
  • Products should take pride in making it so users can explore the facets they care about in a system, without needing to understand the full complexity of the system.
  • Few parts of the product should be inscrutable to non-power users. The best products will help users grow their knowledge gradually.

And because these are often highly technical tools, forward progress requires the technical members of the team to be tapped into the needs of their users, either directly or in collaboration with product and design teams.

Sue's Tweet suggests that we've got work to do changing technical minds.

How we’re applying these lessons at Akita

Especially for my highly technical team, fully shifting towards a “the customer is always right” perspective continues to be a work in progress. We believe the first step is to acknowledge where we might be deficient—and learn from our users (and others!) how we can do better. We’d love to hear from developers and tool creators alike about your perspective on this.

And we’re always happy to get more feedback on our beta product. Our early users have been incredible in helping us figure out how to lighten mental load for users trying to quickly understand their API behavior. We’d love to have you join.

Photo by Ralph Katieb on Unsplash.

Share This Article

Join Our Private Beta now!

Thank you!

Your submission has been sent.
Oops! Something went wrong while submitting the form.