This interview is part of our Fieldnotes series, where we research what leaders are doing to improve the effectiveness, efficiency, and happiness of their engineering teams.
We recently interviewed Kaitlyn Tierney, Staff Software Engineer at Farewill. Before becoming an engineer, Kaitlyn was a librarian, which is helpful context for this piece on documentation. Soon after joining Farewill, Kaitlyn took the project of revamping their documentation system. Here she shares the steps she took, shares some templates she created, and offers ideas for how others can “nudge” teams into the practice of contributing to docs.
For the majority of my career, I’ve worked in fully remote and distributed software engineering teams. When I joined Farewill right in the middle of the pandemic, a company that wasn’t historically fully remote, they were in the early stages of investing in documentation. Knowledge sharing up to that point was mainly happening in the office, although some foundational work with documentation was already in place.
But documentation wasn’t as far along as it needed to be. What that meant for me personally is that it was hard to find the information I was looking for, so I had to constantly ask people questions over slack. That was a contrast to previous places where I’d worked that had a long-standing culture of documentation: I could get questions answered just by reading the Wiki or finding something in our GitHub history.
Farewill had big hiring plans, so I decided to go heads-down on building out a logical strategy and structure for our documentation system. I focused on a few core elements:
There’s a concept in library science that’s focused on grouping things in a useful way. You have to start by coming up with concepts that would be useful first for people trying to find information.
So I came up with a taxonomy of the high-level concepts an engineer needs to know about, which now serve as headings. The headings include Infrastructure, Testing, People, Codebase, and so on. Each heading has sub-topics that serve as folders for more information.
Note: In the screenshot above you might notice we use Notion. Before I started this project, the team already had some docs in Notion, so it was a natural place to structure everything in. I do like the tool in general, though, as it's easy to organize information and has the ability to keyword search.
The guiding principle for what lives in this wiki is that it needs to be evergreen content, meaning it’s relevant for a long time. That’s different from an architectural decision record, for example, which is more of a specific decision that we made in the codebase. That type of documentation lives in a searchable database and doesn’t need to live in this wiki.
One interesting thing I've observed is that it’s hard for some people to naturally understand where things should live. There have been a few situations where someone added something to the wiki and it wasn’t the place that made the most sense. So in situations like that, we talk through it — what’s the purpose of this? Where do you think it should fit and why? Should it be a top-level subject or does it belong nested under something else?
It’s also been helpful for people to use this system to have a page about “how to use the wiki” that lives in the wiki.
As a separate investment from initially getting our documentation system together, I spent some time coming up with writing down guidelines for engineering practices.
Engineers work in lots of different ways, but we need to standardize around a few things, like writing commit messages, the effective use of version control and git, and handling pull requests. So we introduced templates for each of these things: see our template for crafting git commits and the development process.
This is the kind of documentation that increases quality as a whole. It makes the codebases themselves more reliable.
At a previous company where I’d worked, you could go back to the beginning, find a foundational commit, and see in the commit message a thorough explanation on what choices were made and why. So when you had to make changes to that code, you were confident doing it. You understand exactly where the author was coming from and what constraints they were working with. It’s a completely different experience.
So that’s what we were aiming for, at least moving forward, at Farewill. We want commit messages that explain what we've done and why. And really, that should be non-negotiable, but I did have to do a bit of selling the team to get people into that practice.
I shared the new documentation system first with my manager, then at her suggestion shared it more widely in our #guild-engineering slack channel. And people were really excited about it — I was surprised by how overwhelmingly positive the response was.
In terms of building a culture of documentation excellence, Farewill has come a long way. There are a few things I do regularly to encourage team members to write or update docs:
So there’s been a cultural shift but, like anything, it takes constant nudging to keep everyone doing the task.
We do quarterly engineering satisfaction surveys where we ask questions about how people are perceiving the maintainability of the codebases. (We review responses in our bi-weekly engineering guild meetings, and the responses from the questions are used to drive the roadmap for our platform engineering team.)
Below are some screenshots of our scores on Documentation in 2021 vs 2022. (Special thanks to Helena Thompson, who deserves all credit for running and continuously improving these surveys.)
One of the metrics for maintainability is Documentation, and when I started documentation had low scores. Now, we’re scoring highly on that metric across the organization.