I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Marko and Simeon both work at Twitter on documentation projects. About 9 months ago Twitter acquired a software training company Marko and Simeon both worked at. The goal was to create Twitter University for internal training and learning. It didn’t take long, though, for someone to suggest they tackle the technical documentation as well.
The technical documentation they work on at Twitter is internal-facing. It’s engineer-to-engineer documentation and not the public API specs. They ran a survey about the internal docs. Using the net promoter score standard they found that most people hated the internal docs. Some common complaints were that the docs were incomplete, deprecated, non-existant, or unclear.
Their technical docs team was just 3 doc writers. They view the team as the engineering grease internal to the company. The goal is to make things run smoother. To do this they’re making docs like code. The process they’re working toward is to code, test, doc, and then ship.
They’re taking lessons from the test-driven-development shift to bring docs in to that process. Developers at Twitter have gotten accustomed to needing tests finished before they commit code. The challenge is to make that cultural assumption the same around docs.
The plan is three-pronged. The platform is DocBird, the publishing platform. Above that lie self-service tools and templates. Finally there’s DocDay, an internal doc sprint that aims to promote documentation internally. As they got started they realized there was no coherent plan or standard to docs. Different teams used different tools, formats, and processes. Some teams were even using Google Docs. Their internal wiki has more than 60,000 pages across more than 150 spaces.
In treating their docs as code they’re checking the docs in to git, those docs are plain text, and they’re regularly reviewed and merged. This is where technology comes in to the rescue. They built a homebrew documentation platform they call DocBird. They hit a few roadblocks in this process. The fact that DocBird is not a wiki, isn’t ReStructuredText, and isn’t generated from the source code were all initial problems.
Since the docs live in the code repo they’re able to track the amount docs drift away from code. The goal is to keep things in sync, but it’s a challenge.
The template layer of their project is aimed to enabling developers to get to minimum viable documentation as fast as possible. They’re working to enforce consistency in documentation through those same templates; things like a similar language are important here. It solves the problem discussed in an earlier talk about how intimidating a blank page is. By filling some default language in to the template they help developers get over that initial hurdle.
In terms of coverage the goal is to have 100% of known projects covered with the same docs. They’re bootstrapping this by starting with readme files that point to all the docs that exist. They don’t all have to be in DocBird right away.
With only 3 people using resources well is key. They’re pushing education as a way to leverage those three documentarians to have maximum impact. By working on templates, for example, 3 documentarians can influence hundreds of docs. Ultimately better technology alone will not create a culture of documentation.
The key problem is getting Twitter’s thousand+ engineers to write docs. On the one hand they’re telling the engineers that a lack of docs should be considered technical debt. On the other, though, they’re telling the engineers that if they want other teams to adopt their library they need to package it attractively; docs are a key part of that package.