In companies that have large engineering teams, a dedicated technical documentation organization is a necessary function. Our industry's understanding of the role of documentation, both as engineers and technical writers, has shifted its focus over the last decade.
- Troy Howard, Contemporary TechDocs
Yeah, I just quoted myself. That's the least of my worries. My bigger concern is the incredible pile of work awaiting me every time I open my laptop. I long for the day when I finally get approval from upper management for the headcount to hire another documentarian. We could do so much more with just one or two more people.
My boss sometimes asks* me, "I'm not sure if we can get headcount, but it would help if you could tell me exactly what you'd do with more people."
* note to my pedantic readers, I realize that was a statement, not a question, but this is Manager Speak™, not normal English.
I suspect that many of my peers in the tech-comm world are in a similar situation. This series of articles intends to answer that once and for all. First, I'll describe the strategy that enables this kind of scaling, and then give some suggestions on how to grow a TechDocs team from your first documentarian to your hundredth. Finally, I'll discuss some deeper aspects of our experience trying to implement this at Twitter.
A Scalable Strategy for TechDocs
At the time of this writing, Twitter has ~1500 technical employees, but only two (2) full time tech writers. That is a ratio of 750:1. If we are going to have an impact, we're going to need a scalable strategy.
Breaking that down a bit, our team of two is only responsible for internal technical documentation (yeah, the public API docs you all know and love so well are handled by an entirely different crew). Our ~1500 engineers crank out code at a blinding rate. We have roughly 6000 software projects, all of which need to be documented. Currently only ~600 of them are. So how are the two of us going to get the other 5400 projects documented? How are we going to maintain the existing 600 documentation sites? Is it even possible to keep up with this?
The answer is a resounding YES WE CAN (kind of).
The key is to leverage those 1500 engineers to write their own docs. But this isn't an article about how we work at Twitter, or how to fight a losing battle and look fabulous while doing it. Rather, this is an article about how to operate an effective TechDocs organization whether you're 1 person or 100 people, and regardless of how many engineers you are supporting.
Our scalable strategy is composed of three tiers: #WriteTheDocs, Mentorship, Platform and Policy.
- #WriteTheDocs - TechDocs creates and maintains high-impact content. They also design and maintain large scale Information Architectures (IA).
- Capacity/Scale (per person): 1-2 projects per quarter
- Mentorship - TechDocs cultivates a product-oriented engineering culture that values documentation as one of the many deliverables required for a complete product. TechDocs operates as a service agency, providing 1:1 mentorship, editorial services, and prescriptive guidance to engineering teams.
- Capacity/Scale (per person): 4-6 team engagements per quarter
- Platform and Policy - TechDocs provides policy, guidance, and automation tools for all engineers. The tools provided are first-class tools which engineers interact with directly to create and consume docs. These self-serve tools and materials create a platform to improve Information Experience (IX) and raise baseline content quality by enabling engineers to produce better docs on their own.
- Capacity/Scale (per person): 1-2 major tool features or policy/guidance documents per quarter
Here's a fancy diagram to describe it (see below for the more-than-1000 words to explain):
- /\
| /__\ #WriteTheDocs (6 projects a year, ~1% of customers)
Quality | / \
| /______\ Mentorship (22 projects a year, ~5% of customers)
| / \
_ /__________\ Policy and Platform (self-serve, 100% of customers)
|- Quantity -|#WriteTheDocs
TechDocs creates and maintains high-impact content. They also design and maintain large scale Information Architectures (IA).
Mission-critical technologies require the highest possible quality of writing. Since these systems directly affect the daily life of every engineer, your TechDocs team should treat them as a top priority. In such cases, it makes sense to put your best writers on the project and ask them to just #WriteTheDocs.
This process looks like a typical industry tech-writing process. TechDocs first interviews potential documentation consumers as well as subject matter experts (SMEs), then writes and maintains the content themselves.
This tier emphasizes quality over quantity because the high quality docs will have a large overall impact.
A single documentarian should be able to complete 1-2 major writing projects per quarter, or up to 6 projects per year.
Mentorship
TechDocs cultivates a product-oriented engineering culture that values documentation as one of the deliverables required for a complete product. At this tier TechDocs operates as a service agency, providing 1:1 mentorship, editorial services, and prescriptive guidance about docs to engineering teams.
Look, we know what makes engineering teams successful: a product culture. What do we mean by that? We mean that they are focused on creating a complete product that will deliver customer value, rather than just cranking out code, committing to git, declaring themselves "Done!", as they walk off victorious into the sunset.
When teams think about their work as a product for a customer, they realize that there's more to a product than just code. Teams that have a product culture recognize the importance of things like unit tests, excellent UX, technical support, release cycles, and that vital linchpin that holds them all together: documentation.
The goal of TechDocs at this tier is to mentor engineer teams with the intent of cultivating a stronger product culture. Sometimes your TechDocs team will talk about culture directly, but often you'll just serve in an editorial or advisory role. When you have our mentorship hat on, you'll field inbound requests from teams for help. You don't write the docs for them, but you will help them to write them. This kind of direct engagement with a team still takes a lot of effort and time. When the ratio of documentarians to engineers is high, you won't be able to mentor every single engineer, or even every team.
Mentorship is reserved for projects that will impact a large number of engineers. TechDocs should look to support teams that create and maintain engineering platform tools like continuous integration (CI), storage, data science, etc. Teams that service other teams have a force-magnifying effect. The effort that is put into those teams will result in other teams becoming more effective, and others will look to them as role models for team culture.
This tier values quality and quantity equally, attempting to achieve a balance between both.
A single documentarian should be able to complete 4-6 team engagements per quarter, or up to 24 engagements per year.
Engaging with Engineering Teams
When you engage with a team, you will evaluate team culture, review their existing docs, establish measurable success criteria (so that you can talk ROI with real numbers), and then make a specific list of tasks to fix up the docs. Team engagements like this are limited to only two (2) weeks.
Assigning a Documentation DRI
One of the first steps in addressing team culture is to identify (or appoint) a Directly Responsible Individual (DRI) for documentation. The goal is to leave the team with an independent and sustainable process for creating and maintaining docs. The Docs DRI will be your point-person, acting as the primary documentation advocate on the team, and as a watchdog who makes sure that doc development continues to happen after the TechDocs mentor moves on to the next thing. After the docs review, give the team's Docs DRI a list of doc-improvement tasks.
Put A Number On It
The next step is to establish success metrics. I like to call this process "Put A Number On It". Working together with the Docs DRI, determine a set of success metrics that makes sense for their product and a figure out a process for measuring those metrics (e.g. performing stakeholder surveys or customer usage studies). Before work starts, measure the baseline for that metric. At the end of the engagement, measure the same thing again to quantify the improvements. When you need to prove the value of working on docs and are asked "What is the Return On Investment (ROI) for this?", you can use these numbers to show how much improvement came from your work, comparing that to how much effort was put in. This almost always works out for the best and creates a compelling story for future investments in documentation.
Wrapping It Up
After two (2) weeks it's time to wrap it up and walk away. During the next month or two, the engineering team takes ownership of the remaining tasks, but the TechDocs mentor will serve as a project manager, making sure the project keeps going and stays on course. You might file tickets in an issue tracker, or send out nagging emails, or stand outside their house wearing a banana-suit. Whatever it takes to get their attention.
Option: Embedding on a Team
Some high-impact teams may need a more intensive engagement. In those cases you might need to embed on the team for up to a month. When embedding, you act as a member of the team. Defer any other work that is not related to the team, go to all their planning meetings, sit with them in their area of the office, and generally attempt to operate in exactly the same manner as any other permanent member of the team. This is the the most effective and direct way to change a team's culture.
Note: This differs from work in the #WriteTheDocs tier, because while you may end up writing some docs, your goal is not to produce docs, but rather to impact the culture of the team. You may need to write docs to kick-start that culture, and to provide a good example, but that's not the main purpose of your presence there.
Doc Days: Company-Wide Mentorship Events
Another activity that falls under this tier are Doc Days, which are day-long documentation mentorship events that any engineer can attend. Read more about Doc Days here: How To Run a Doc Day (coming soon!)
Platform and Policy
TechDocs provides policy, guidance, and automation tools for all engineers. The tools provided are first-class tools which engineers interact with directly to create and consume docs. These self-serve tools and materials create a platform to improve Information Experience (IX) and raise baseline content quality by enabling engineers to produce better docs on their own.
Not every project or team needs hands-on attention from your TechDocs team. Sometimes they just need a little guidance and tooling – metaphorical signposts and guard rails – to help them do a better job of writing docs on their own. A TechDocs team can (and should) build a platform composed of policies, best practices, templates, and automation tools that engineers can use on their own without help from TechDocs.
This tier values quantity over quality, to have a wide impact and indirectly raise the quality floor.
A single documentarian should be able to complete 1-2 major improvements to the platform per quarter, or up to 6 platform improvements per year.
Policy
The first thing you should do when building a platform is establish clear policies. Policies enforce basic requirements, reduce ambiguity, and facilitate easy decision making. The kinds of policy we're talking about here are things like a company-wide Documentation Style Guide, direction on which tools to use, and standards about how documentation should be prioritized within engineering teams.
Guidance
The next thing to do is to provide some guidance. Guidance involves prescriptive docs about writing like "How to Write an Outline" (coming soon!), as well as descriptions of processes for maintaining and testing documentation and of preferred team culture. Another great form of guidance is a corpus of documentation templates that engineers can work from. The ultimate goal of these resources is to improve consistency and facilitate action, by removing the barriers to creating good quality documentation.
Tools
Last but not least are hands-on tools that engineers use to read and write docs. This can be as simple as setting up a wiki or knowledge base for the company, to custom-made documentation generation systems which automatically build and publish docs from a source code repository. Tools raise the quality floor, automate complicated workflows, facilitate information discovery, and help to maintain awareness of documentation health over time.
Tools can be used to automate/improve:
- Publishing: Improve consistency, ease discovery, and align with culture
- Consistency: All the pages look the same, due to a common theme and unified project list
- Discovery: All project docs are in the same tool, with well-structured IA and search capabilities
- Culture: Use git on the command-line, ease collaboration, reinforce company identity, etc.
- Linting (structural analysis): Improves consistency by detecting obvious defects like:
- Spelling and grammar errors
- Missing content
- Privileged or inappropriate content
- Non-optimal reading level, reading length, etc.
- Search: discovery
- Health and Awareness: Improves culture-of-docs via:
- Notifications: Reminders for doc owners to encourage on-going maintenance
- Reader Trust: Healthy, Verified, or Highly-rated docs are obviously marked
- Author Pride: Report on readership traffic, quality metrics, user sentiment, etc.
- Increased Awareness: A central location for docs encourages "sideways discovery" of other docs
- Templates: Improves consistency and quality by providing a fill-in-the blank experience
- Metrics: Easily generate reports about a single project, or all projects to understand the overall condition of the documentation. Good metrics make it a lot easier to plan and discuss work at the managerial level.
Next Step: Growing Your Team
Now that we've described our scalable strategy, the next part of this article will walk you through How to Grow a TechDocs Team, from your first documentarian to your hundredth.