3 min read

Soapbox: How can I rtfm if you didn't wtfm?

How can I rtfm if you did not wtfm? A question for the ages
Soapbox: How can I rtfm if you didn't wtfm?

RTFM - read the f***ing manual WTFM - write the f***ing manual

I! love! documentation!

Serious woman in some type of legal office saying "Document Everything."

From my first year on the job to present day I love well-crafted documentation site. Bonus points if its embedded/accessible within the product vs. a standalone separate site.

The only thing worse than shitty documentation imo is no documentation.

Its also why I love distributed traces. They empower a real-time architecture diagram and model focusing on the interdependencies rather that a siloed view from one component's perspective that need to be carefully (and horrifyingly sometimes still manually) stitched together to build an somewhat comparatively lesser representation.

OK double-clicking into that more its because people do not like/have time/have knowledge/have sufficient context doing the manual stitching of things or have had to work at the company over a long period of time gaining institutional system knowledge plus curiosity and expertise to build a more comprehensive north-south and east-west view of the system.

So when you onboard to a new company, as many many people are about to and in the midst of doing.....for companies with little existing documentation or cohesive monitoring/instrumentation strategy even a 3 month learning period before joining an on-call rotation can still feel like "gl;hf" (good luck, have fun)

As someone who likes documentation in all forms, in line, the occasional comment, guidebooks, tutorials, official project docs, internal handbooks, run-books, IRL books, white papers, memes, videos, etc.... during my onboarding I inevitably end up asking where to find documentation, system overview, where can I read and learn and study the pile of code and config that interfaces with this complex running system in the cloud. the thing i'll ultimately be on-call for.

and I've been confronted with many of these answers

"There's no time we needed to get this out the door"
"No one reads them." a variation of "I don't"
"They get stale like the nanosecond after you publish them" aka nihilism-as-a-service
"that's not my job"
"i hate confluence/wiki-of-your-choice"
"its just an internal temporary tool"
"the official docs are good enough"

a visibly annoyed Kristin Wiig on SNL making a "can you believe this BS?" face

All of those really steam my broccoli so I asked dear documentarian and former colleague, Victoria Bortle what were some solid reasons to consider about the value of documentation and wihtout skipping a beat she gave these excellent answers

3 Reasons To WTFM

  1. Training - New folks will have
    resources where they can up to
    speed quicker and contribute to
    team goals sooner.
  2. Scaling & collaboration - Teams
    will have resources they can point
    other teams to. For example, a
    "roles & permissions" doc can be
    used by folks across multiple teams
    (QE, Customer Ops, Backend Eng.,
    etc.). When new solutions need to
    be considered, those docs can
    serve as a starting point (gets
    everyone on the same page) to kick
    off brainstorming for enhancements
    and features.
  3. Troubleshooting & handoffs -
    Stuff happens, and sometimes
    happening with little to no notice
    (parental leave, illness, resignations,
    natural disasters). Having an accurate set of docs helps
    safeguard information and prevents
    teams from losing the ability to
    execute (with or without key


xoxo paigerduty