Further Discussion
While writing these articles, I asked my coworker Greg Poulos (@gregpoo) to take a pass at proofreading/editing. He had some good feedback and questions, which I thought I should tack onto the end of this series of posts.
NOTE: This is the third article of a three-part series. The first part discusses strategy while the second part explains how to grow a TechDocs team.
This discussion will be formatted as a dialog, with Greg providing feedback on the previous material, and Troy responding. *
Problems with Mentorship
Greg: This is really great! Very clear, straightforward explication of our approach to TechDocs. I feel like we can actually take some lessons away from this post for our own organization :-)
The thing that struck me most was that this post doesn’t really mention the difficulties we’ve had in implementing the three-tier approach. In particular, I feel like we’ve had trouble at the Mentorship tier.
Troy: Excellent point! I agree that we really need to look at this as a vision for our team and examine how far we are from it. I think a lot of the difficulties we've faced with the three tier approach are more related to our team size, and more specifically with our ratio of 1:750. Part of the idealism of this post is the notion that a TechDocs team grows with a company, so that you never experience the kind of excessive ratio imbalance we deal with here at Twitter.
According to the blog post, we're expecting to be able to mentor three (3) teams per quarter. We've done a great job of keeping up with that. Considering Twitter has hundreds of separate engineering teams, even when we meet that goal, it is hard to see the impact. That's why we focus on strategic projects that will have a force magnifying effect, and build our own success metrics around scoped impact.
Regarding the problems we've had with mentorship… They fall into three large categories of failure:
- Ownership: Teams don't have a strong sense of ownership of their docs. We engage with the team, do some work for them, and they are happy to let us do the work, but then they don't follow-up to maintain and own their product docs long-term.
- Prioritization: Initial conversations go well, but we can never seem to get the team to prioritize the docs project. We assign work for them to do, but they don't do it. Overall very little accountability for this failure. No one ever explicitly says that the work won't be done, but it just keeps getting "put off", despite our influence/nagging.
- Poor ROI: Teams feel that the Return On Investment (ROI) of doing docs-related work is too low. They feel that the investment in terms of time/effort is too high, compared with the gains in customer experience/value. They explicitly walk away from doing docs work (even when guided by or in collaboration with the TechDocs team). The team leaves with a sense that it wasn't time well spent, and are less motivated to work on it again in the future, or maintain the work they did.
For each of those problems, there are solutions.
The Docs DRI concept directly addresses ownership issues. Once the Docs DRI role is assigned, that person can be an embedded documentation advocate, pushing back against prioritization failures, by regularly bringing up the need to do docs work during the team planning meetings.
When we've used the embedded model, we become the de facto Docs DRI for the team, and we've had much better success that way. Another technique to combat prioritization failure is regular follow-up on issues/tickets that relate to docs, instead of letting them go stale. This can be automated, or manually done by the TechDocs team (it may seem like boring grunt work, but is important organizational communication!).
Regarding ROI and how working on docs is perceived by Engineering teams, the best approach is to lead with numbers. By performing before/after studies, you can prove the value of the work done on docs. I'll follow-up soon with a blog post dedicated entirely to that. The important part here is discerning between perceived lack of value vs actual lack of value.
In other words, it's certainly possible to spend a lot of time on docs and get nothing out of it. If that's happening, then that's a problem and should be fixed. If it's just a matter of Engineers and Engineering Managers perceiving a low ROI, when actually the customer impact of docs work is entirely worth it, then it's up to the TechDocs team to prove the value of that work by quantifying that impact and showing up with numbers that will shift opinions.
Engineers respect numbers. Give them numbers!
Shouldn't We Allocate More Resources to Writing vs Mentorship?
Greg: *I really enjoy the whole "How to Grow a TechDocs Team" section, and the specificity with which you go through what should change with each additional member. My main note here is that, at the largest levels of organization, I might push to focus more resources into *Writing and fewer into Mentorship.
E.g., if we had 20 TechDocs people at Twitter, I feel like we’d be better served to have 2 Mentors and 8 Writers rather than 5 Mentors and 5 Writers. Or maybe there could be more of a focus on crossover roles in the larger organization size — e.g., folks who are 75% #WriteTheDocs and 25% Mentorship
Troy: I intentionally emphasized Mentorship over Writing, because I feel like it's always important (and perhaps increasingly important as a company grows) to encourage a culture of docs in engineering teams.
A company should never let the engineers feel like they can stop taking ownership for their own docs. I strongly feel that writing is a core skill and fundamental aspect of good engineering. Within technology companies, tech-writing as a separate independent discipline is primarily meaningful as a quality boost for high-value information products.
There is a danger with having more dedicated writers, which is that engineers may feel like they can specialize more and do less writing, since the TechDocs team has more capacity for it. That can cause a pendulum swing wherein technology gets created and a minimal TechDocs team is overwhelmed. This is assuming that the writer to engineer ratio is still in the 1:20 or 1:10 range. If it's closer to 1:1 or 1:5, then the writers may be able to keep up, but maybe not.
However, I also pessimistically believe that no tech company will ever value tech-writing equivalently to engineering, which means that there will always be a large differential ratio between writers and engineers, at least an order of magnitude, if not two. Of course, if that ratio does fall into that 1:5 to 1:1 range, by all means, tech-writing should take full ownership of the docs and leave the engineers to crank out code (assuming they will still meet with writers as SMEs, which may take as much of their time as just writing basic docs anyway… sooo, maybe not very efficient anyway?).
There is also a loss of resiliency when specializing vs generalizing. Many tech companies suffer high employee turnover rates, and reduction in force (RIF) events that eliminate staff who do not contribute directly to revenue generation. In such cases, imagine that you had a team with 10 dedicated writers, and a team of 20 dedicated engineers who did no writing. Suppose you lost headcount for both writers and engineers, but lost a greater percentage of writers, and ended up with say, 5 writers and 15 engineers. Since your engineers have not been working under a culture of docs they won't naturally pick up the slack and start writing more, especially considering they just lost engineers and will need to increase their workload. Further, your team of writers will get quickly overwhelmed, without time for mentorship, and will be demotivated by their loss of staff. You may even lose the rest of those writers in such a situation.
Now imagine that same situation, but 5 of those original 10 writers spent their time mentoring the 20 engineers on writing, and encouraging them to spend 25% of their time on writing. The engineers are now producing 75% of their max engineering output (15 engineers worth), and the writing output remains the same (because 25% of 20 engineers == 5 writers worth of output, plus the other 5 writers). This may seem like a loss of engineering productivity, but it's actually a gain in resiliency. When the RIF comes and the TechDocs team is reduced to 5 and the eng team to 15, the engineering team can continue to produce 3.75 writer's worth of output, plus the 5 fulltime writers, leaving you with 8.75 writers and 11.25 engineers worth of output. That is a much more balanced portfolio.
I'm also implicitly prioritizing quantity of output over quality and long-term resiliency over short-term impact. That may not always be the right set of values. Depending on the phase of the company, and the long-term and short-term goals of company, they may wish to focus on maximizing quality of writing on certain high-value topics. For example, a company that produces an API-driven product, when it is first building its market and attempting to rapidly acquire customers, should probably dedicate their full-time technical writers towards producing the highest possible quality of public-facing docs, since that's the only interface the customers will have.
Conclusion
I make some strong statements above, but please remember to take it with a grain of salt… all of this is entirely based on scaling a set of random assumptions about potential productive output, with no real data to support it. That's why I really want to measure real output via the Codewerdz project. I want more legitimate numbers about both what engineers can/will do and what tech-writers can/will do.