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!

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"

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
   players).
   

CAT TAX

xoxo paigerduty