Benevolent RTFM

Jan 27, 2021 - 4 min read (632 words)

The bigger the team, the harder the communication is.


Image Title

(image source: Lighthouse)

I was recently discussing with one of my mentors about the importance of some critical reference documentation. And also about the necessity of repetition in communication.

And an idea came while I was consolidating my meeting notes later on.

I slept on it, and it came back again, so I'm writing a short (or not) post on it.

RTFM or Read The F*cking Manual. A pretty old, and standard answer you can get when asking for a question already documented. It initially comes from a LINPACK user's manual in 1979.

Informing someone that the answer to his question exists in dedicated documentation is ok.

But the form is the worst we can find. It can make someone feeling guilty for asking something. It should never happen; any questions are right to ask; each answer brings value.

What about transforming this old RTFM thing by adding a critical missing aspect of it: be kind, be benevolent.

The Benevolent RTFM enters into the game with the following pseudo-framework.

1/ Refine the need.

Questions about What?

  • What are the recurring questions? How often are they asked?
  • Who asks? Individuals, roles, teams. What are their needs?
  • Where are they asked? What's the medium? Meetings, email, slack channel, calls, etc.
  • When are they asked?
  • Who answers, who can answer, who should answer?

Any reference document?

  • Does it exist? Is it known and easy to find?
  • What's it's goal or intention?
  • For which public?
  • Is it up to date? With an understandable format and content?
  • Who maintains it? How often?

Answering these questions, we can define if there is a need to create or improve or better communicate on a piece of documentation. We specify its goal, for which public, for what expectations.

2/ Make the documentation enjoyable.

It's now time to make sure that the ownership of the documentation is clear, that the content answers the goal, that the format is pleasant, its title is self-explicit, that the doc is up to date, and available for the given public.

3/ Make the documentation known.

We're entering into the best part.

You can start answering questions with a kind message and a link to the specific section of the documentation.

Another critical point is to start to reference this documentation into as many other docs or decks you present and share (when it makes sense). Like if you were following a search engine optimization strategy. Make sure that this link will always be valid.

4/ Measure the progress & adapt the content.

A lot of documentation tools include some read statistics, to know who access the doc, and when. The number of accesses of the targetted public over time is a good measure of progress. The amount of positive feedback is an even better measure.

Use the feedback to refine the needs and update the content or format accordingly.

The real magic happens when the documentation starts to be openly shared, as an organization reflex, and this, totally out of your control or actions.

You created self-service documentation.

Last words.

While growing, as a company or as a team, we need to shift our communication from oral to written. Knowledge sharing practices have to change; small chats at the coffee machine are not good enough anymore.

Building solid documentation practices and habits become a critical asset.

This Benevolent RTFM naming made me laugh. So much contradiction into these expressions.

The main point is we should share what we know, openly, kindly, and generously. And at a particular team scale, creating a referential is the most impactful way to reach this goal.