The three docs I made for me that people keep using.

As a tech writer, I wrote a lot of documentation. It was, in fact, most of my job. As a software engineer and now engineering manager, I think I may actually write more than I did as a tech writer. Most of those documents are meeting notes, project plans, scopes, and specs, but there have also been a generous handful of docs thrown together for my own reference… and time and time again, other people have found them and started using them.

My Best Docs

Allison’s List of Properties

“Allison’s List of Properties” was, as its name suggests, a list of sites (docs “properties”) that my team was responsible for, the URL of that site, the github repository in which its content resided, whether it built on the old tooling or new, etc. I’d add new columns from time-to-time when I needed another one.

One day, a team member messaged me to let me know that the site list was missing some of the newer products. This surprised me, since I wasn’t aware we had a site list and asked for the link. They sent me the link to “Allison’s List of Properties”. I explained that “Allison’s List of Properties” was just a doc I’d thrown together some years back for my own reference. They explained that they’d been using it for months whenever they needed to look up where a site’s content lived.

Upon further discussion, it turned out that my whole team regularly referred to that spreadsheet because it was so helpful. I gave everyone edit access and gently encouraged them to help keep it up-to-date. I (with some sadness) renamed the spreadsheet to “Docs Platform Properties” and moved it into the shared drive, where it lives to this day.

Allison’s Monitoring Dashboard

Charts is a data visualization tool for working with data in MongoDB. My team's build data is stored in MongoDB. As the lead of the team responsible for build infrastructure, performance, etc., it’s helpful to monitor our build data. Years ago, I created a basic dashboard with a few charts:

• Recent production deploys (a list from the past week so if something looks weird on the site I can easily see when it was last deployed)
• Build speeds over time (a scatter plot of all of the end-to-end build speeds for the past year so I can see if there are any performance issues we need to look at).

When I had a question that I could answer with our build data, I'd add another chart, such as:

• Average time spent in queue this week vs. last week (this mattered a lot when we were trying to reduce queue time).
• Humans who have used a deprecated webhook in the last week (so I can gently encourage them to move to the new webhook so that we can remove the old one).
• Average build speed per property this week vs. September 2023 (the hope was to see a smaller number).
• Every failed build job (why were they failing?!).

From time to time, a stakeholder would ask me about recent prod deploys or build speeds or time in queue and I’d pull up the dashboard to show them the data, and I’d think nothing of it. Then, one day, my VP asked me for “that great dashboard showing build speeds improving” and I thought “Do we have a dashboard for that?” only to realize the dashboard in question was the one I'd thrown together for my own quick reference, which was now being screenshotted and shared well above my pay grade.

It’s incredibly easy to think that the thing you create for your own purposes has no value beyond yourself, but time and time again, I’ve found that the simple docs I create for nobody but me end up having much broader lives.

Environmental Disambiguation

I’ve written before about my dev-stage-prod environment naming problems. Keeping our infrastructure straight in my head wasn’t working, so I wrote up a quick reference table describing each environment, the S3 buckets associated, the CDN URL, etc. Like “Allison’s List of Properties”, the infrastructure information lived in various locations (source code, config database, the brains of the engineers who'd been around when we set things up, etc.) but it was a lot easier for me to have a clean and simple view I could pull up when I was uncertain.

My Environmental Disambiguation document ended up a page in our team wiki, and has gone on to have a life of its own, with additional information added, a proposed new environmental naming scheme, links to the code and config, and so on. It has made onboarding team members inordinately easier.

What’s Next?

The list of properties, monitoring dashboard, and environment cheat sheets I created live on, and they’re better and more useful because more folks regularly use them and keep them up-to-date. Recently, a few team members put together an updated infrastructure diagram for their own use. They shared it with the broader team and I’ve now used that document when working with two different external vendors to quickly and easily explain our system. That’s a huge impact from a diagram thrown together for personal use!

Earlier in my career, I often assumed I was the only person who was confused or was the only person who couldn’t keep XYZ straight in my head. At this point in my career, however, I’ve been shown time and time again that the solution to my problems is often the solution to many other peoples’ and that sharing that simple solution can be a force multiplier for my team.