Investing in Internal Documentation: A Brick-by-Brick Guide for Startups

David Nunez, an early hire at Stripe and Uber, shares his step-by-step playbook for establishing good internal documentation habits at your startup. He unpacks his tested tactics for creating a culture of documentation, setting the quality bar and keeping things organized.

Outline

It’s the middle of the night when the on-call engineer jolts awake as their phone flashes and chimes with a flurry of push notifications, text messages, and phone calls. The production server is down and they’re responsible for getting it back up as fast as possible. With bleary eyes and a foggy mind, the engineer frantically searches for answers in Slack, Google Docs, and GitHub but they only turn up vague mentions of the error. With no meaningful information to orient around, they’re forced to wait anxiously for one of the veteran engineers to wake up as the outage drags on.

Mission-critical knowledge trapped in an early hire’s head is an all-too-common problem that startup engineering orgs know well. But investing in internal documentation is often a chicken-and-egg scenario. In the earliest days of a fledgling business, there’s a golden opportunity to write things down in the moment as you’re gaining valuable knowledge and charting your course. Each new hire who joins quickly takes on heaps of responsibility, and these documents can be a critical resource for getting up and running quickly without slowing down the pace of business.

But with a bafflingly long to-do list and small teams, carving out time to document these lessons quickly falls to the wish-list pile, and those best-laid plans to write as you go tend to evaporate. Put on the back burner, these critical insights are lost to time.

As an early docs leader for companies like Stripe, Uber and Salesforce, David Nunez has seen this cycle repeat time and time again — and he’s often been brought in with the mandate to clean up the internal documentation debt. (In the spirit of practicing what you preach, Nunez even wrote down his lessons, co-authoring the book “ Docs for Developers,” a handbook for technical writing.)

STEP 1: START WITH A CULTURAL SHIFT.

Documentation is often seen as a nice-to-have — a can you can kick down the road until "you have some free time," or, worse, until a critical outage forces the organization to reckon with it. “A lot of times people wake up to the need for documentation resources when something terrible happens and things go perfectly wrong,” Nunez says.

Uber is now famous for how it deployed meticulous internal playbooks for launching its service in a new city. Employees could land in a city with no Uber footprint, armed with a playbook chock-full of documentation on what had worked well in San Francisco and New York. But despite these early wins, the company got a painful wake-up call that they needed to invest even more in internal documentation.

“At Uber, we were starting to pay attention to documentation and assembling some resources, but the engineering team was growing way faster than the documentation team could keep up,” says Nunez. “Then there was an outage because a data center in China was overheating. An engineer followed the steps in the runbook, and they actually made the outage worse and totally melted down the data center.”

A root cause analysis uncovered an unlikely culprit. “The runbook was inaccurate and had the steps listed out of order. The runbook was obviously very sloppily written, and it woke leadership up that we needed to get a handle on our documentation standards,” says Nunez.

It might seem like the immediate fix is hiring folks to solve the problem. But rather than kicking off a recruiting sprint to find your first documentation hires, Nunez suggests a different approach. “The default is that companies under-resource documentation efforts which, of course, leads to weak documentation. But I’ve also witnessed companies that do throw a lot of money at documentation, but not in the right areas or with the right approach, so engineers don’t regularly use the docs,” he says.

“ I wouldn’t recommend early-stage startups just go out and hire a full-time docs writer. I’ve learned that, especially in high-performance environments, changing the culture is the highest leverage investment you can make,” he says.

Model good writing habits.

“ You can’t have a strong documentation culture without a strong writing culture. The most effective approach I’ve found in embedding this into your culture is ensuring that leaders, from the founders to the frontline manager, take their own writing seriously,” says Nunez.

Try these two regular habits for getting started:

Recap regularly. “The most effective way for leaders to sharpen and exemplify their writing and knowledge-sharing skills is to take meeting notes and follow-ups more seriously. Sharing your own action items and takeaways from the meeting will give others a nudge to model this behavior.”
Get existential. “What did you learn recently? What is your interpretation of current company goals? What recent shifts have you made to the strategy? Sharing musings on a regular cadence offers important context, and they also reinforce the importance of writing and sharing knowledge, which will trickle down to the rest of the org.”

Get in the habit of editing.

“Going back to school, you typically had the Scantron crew, who were happy when a test was multiple choice. And then you had the paper crew, who were happy when they could write an essay. Usually, this was very polarized,” says Nunez. “People who don’t think they’re great writers tend to write less and less and are terrified of having their writing critiqued.”

But editing is critical to the writing process — whether you’re a natural with prose or always dreaded writing essays in school. “Every professional writer has had their writing picked apart over the years, from their professors to coworkers and peers. They accept that it’s just part of the writing process to produce something that’s of high quality. Letting others critique your writing is a vulnerable position to be in, but practicing your writing and getting feedback is the only way to get better,” he says.

Make writing a part of the job ladder.

Eager to fix their flawed internal docs, plenty of leaders jump right to tactics — trying to build the perfect process for baking docs into the software development cycle or swapping out a tool hoping it solves the problems.

Instead, start further upstream: with your hiring and promotion processes. “I’ve found that if you codify knowledge-sharing expectations in job descriptions and job ladders, folks will inherently look to fulfill those responsibilities on their ladder,” says Nunez.

STEP 2: GET STARTED PAYING DOWN YOUR DOCS DEBT WITH A MVP APPROACH.

Even with a cultural shift in motion, you’re likely still facing down tons of documentation debt that’s built up after months (or years) of deprioritizing this work. It may feel like trying to get a 16-wheeler to make a sudden U-turn.

Nunez suggests navigating this bend gradually, so as to not tip the truck over. Start by identifying the most critical topics to tackle first. “Send out a survey to engineers, or look at the most common internal questions popping up in Slack. You’ll likely have 100+ topics with poor documentation that engineers complain about, but in the beginning, you have to align most of your resources behind a narrower focus. Try to identify the top five to 10 technical topics that engineers are struggling with the most and invest in those,” he says.

Resist the urge to just make assumptions about what folks need. “When we were getting started with this work at Uber, we looked at the internal data for what engineers were searching for the most, and the data really surprised us,” says Nunez.

Focus on quality, not quantity to set the bar.

As a bonus, by identifying the most critical topics, you’ll make more meaningful progress faster and develop high-quality examples of documentation that others in your organization can emulate. “When you start focusing on documentation, justifiably, engineers are going to say, ‘I've never done this before. Give me an example.’ By putting more effort behind fewer, high-quality resources, you show people what ‘great’ looks like. You raise the floor really quickly,” he says.

He shares an example for building this muscle memory from his Uber days. “At the very beginning, we started with a document simply on how to set up your environment and set up your dev box so you can actually start committing production code. It was a task that every new engineer would have to do, and without the documentation, folks were just sitting in a room helping the new engineer do it manually.”

“Once we helped that team create a clear getting-started guide, that was well-organized and easy to read, we were able to use that as a golden reference for other teams looking to pay down their documentation debt,” says Nunez. Other ideas for getting started with your documentation include:

Code style guides: “Standardizing your coding styles reduces cognitive overhead during development and code reviews and creates a much cleaner codebase.”
Glossary: “Every company has their own terminology and vernacular for systems and services. Creating a glossary is such a simple way to create a source of truth for important definitions.”

Act as a journalist.

Simple topics like setting up your dev environment can be fairly straightforward. But others (like Nunez’s earlier example about an arcane server management technology) can be much more complicated to start capturing. Rather than tracking down scraps of outdated memos, mixed with emails, Slack messages and emails, Nunez suggests finding one source of truth.

“We would sit down with the person who had the most knowledge on the topic and whiteboard to get the main points down. Then the doc writer would have a genesis of a document and probably a handful of other engineers’ names as leads for more information. Pretty quickly, you’d publish a documentation set engineers could rely on that didn’t exist before,” says Nunez. “Great doc writers act like journalists — following a lead and filling in gaps to create a full story.”

Empower your senior engineers.

As you climb your way out of your documentation debt, rather than anointing one person on the team as the documentation deputy, Nunez strongly encourages bringing senior folks into the fold.

“Educate your senior engineers and hear them out on what they need to help build a strong documentation culture, and keep up a dialogue to maintain these new norms. Having senior engineers enforcing doc standards during architecture discussions and code reviews is a great way to solidify documentation in the development lifecycle. Pretty quickly, it will be so commonplace that engineers won’t even think of it as an extra step anymore. And new engineers who come in will quickly follow suit,” he says.

STEP 3: STOP THE RANDOM ACTS OF DOCUMENTATION AND GET ORGANIZED.

Getting into the habit of writing things down is just half the battle — organizing your docs in a logical, easily-searchable manner is another stumbling block engineering teams face. Without an agreed-upon organization system, you’ll find yourself with an ever-expanding pile of docs with no sense of what’s current and accurate.

Assemble your list.

Start with the organization basics, rather than trying to get too complex too quickly. Just put all of the important docs that you have listed in a spreadsheet. The goal here is to centralize everything in one place, rather than having folks commit “random acts of documentation” that become a disorganized mess.

Onboarding documentation. “These types of documents are often overlooked, but they are just as, if not more important, than any other type of content. Onboarding docs create an efficient path for new hires,” says Nunez. He suggests a low-lift, unstructured method for getting started: “As you grow your team, ask each new hire to just write down what they’ve learned after the first few months. Each hire will build on what was documented before. After just a few hires, that’s a really solid onboarding guide,” he says.

Identify ownership.

You can spend hours of time assembling a thorough, clear document. But too often, folks skip over one of the most important components: The author name. “You can get fancy with a ledger that records which team owns which document, but even if you manually input a team name at the top of a document, you’re creating more accountability and also allowing people to track down the team if a doc needs updating,” says Nunez.

Don’t be afraid to delete.

His biggest piece of advice for keeping your docs organized? Empower folks to delete. "Whether it’s realizing that a document explains a system that doesn’t exist anymore, or a doc is completely out of date, people are terrified to just delete a doc, even if it confuses your engineers and muddles search results. At the very least, you should archive it. You’re making the overall system better by removing things that are no longer useful,” says Nunez.

Level up with landing pages.

After going through the spreadsheet organization exercise, Nunez is a big proponent of landing pages as a way to level up. “Landing pages are often overlooked, but easy to make and highly valuable. These are the guideposts at each major user decision point,” he says.

STEP 4: BRING DOCS INTO THE DEV CYCLE — DON’T WAIT FOR CODE-COMPLETE.

So far, we’ve discussed fixing your documentation debt by writing up missing docs and organizing them in a way that makes them easy to track down. But truly finding doc nirvana requires moving from a reactive to a proactive documentation habit. That means documenting while developing a new feature, rather than just saving it until the end after launch.