Revamping engineering documentation: Farewill's process

For the majority of my career, I’ve worked in fully remote and distributed software engineering teams. I joined Farewill, a company that wasn’t historically fully remote, right in the middle of the pandemic they were in the early stages of investing in engineering 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 was 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 cultures of developer documentation: I could get questions answered just by reading the wiki or finding something in our GitHub history. 

Tactics that helped revamp our documentation structure

Farewill had big plans to hire developers, 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: 

1. Define a logical structure.           

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 makes it 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 technical 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.

‍

2. Create templates for codebase-specific documentation.           

As a separate investment from initially getting our documentation system together, I spent some time coming up with writing 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 understood exactly where the author was coming from and what constraints they were working with. It was a completely different experience. 

So that’s what we were aiming for, at least moving forward, at Farewill. We wanted commit messages that explained what we’d 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. 

3. Introduce the new system and nudge people into the habit of using it. 

I shared the new documentation system first with my manager, and 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: 

• Ask team members to update docs in Slack when conversations are happening. When I see people talking about something on Slack that I know has relevant documentation, I’ll add a note with a link saying “Hey, can you update the doc on this?” It’s always well received. 
• Pair with more junior engineers or newer engineers. Sometimes people don’t contribute to docs because they haven’t developed the skill. I like to pair with people to help develop those skills and their confidence in writing documentation. 
• Ask questions about under-documented areas. Early on in this project, I started talking with the people who were responsible for maintaining the codebases that were not very well-documented. In those conversations, I’d work in a “you know, it’d be great if there were some docs on this. I’ve made an empty page where we can fill it in.” 

So there’s been a cultural shift but, like anything, it takes constant nudging to keep everyone doing the task. 

Measuring success

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

‍

Documentation is one of the metrics for maintainability, and when I started documentation, I had low scores. Now, we’re scoring highly on that metric across the organization.

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. ‍

Kaitlyn Tierney is a Staff Software Engineer at Farewill. Before becoming an engineer, Kaitlyn was a librarian. Soon after joining Farewill, Kaitlyn took on the project of revamping their documentation system. She shares the steps she took, some templates she created, and some ideas for how others can “nudge” teams into the practice of contributing to docs.

‍