How to create a culture that makes information accessible to developers
Companies are often forced to make trade-offs in their areas of focus during growth phases. With growth comes constant change in processes that often puts strong documentation and training on the back burner. In the moment, it’s easy to see it as cheaper and simpler to answer questions one on one than to spend the time to write a document that will become outdated quickly.
The result is an organization that does not scale, due to developers being overwhelmed by similar support requests from multiple parties. These requests could be better solved by documentation and training. We experienced this problem firsthand during LinkedIn’s long period of hypergrowth. To address these issues, we created a new Developer Information organization, the goal of which is to increase the productivity and satisfaction of our developers by making it easier to quickly find answers.
During the early days of LinkedIn, the technical documentation team consisted of a single employee whose job was to create documentation for our internal IT help desk. The responsibilities included documenting IT procedures for how to help LinkedIn employees and how to update systems. After about a year, a second technical writer joined LinkedIn to document a new presentation framework, and not long after that, a third joined to work on the analytics platform. These writers weren’t originally on the same team, but they came together to create documentation for our technical priorities. This team didn’t grow at the same rate as the rest of the company, however, and as a result LinkedIn struggled to scale documentation.
Challenges during growth periods
We started to hear from our engineers that the sporadic documentation was becoming a bottleneck that slowed their ability to use internally built technologies and tools. The inconsistency in documentation meant that developers could not trust any answers they did manage to find on their own—even if those answers were actually correct.
This was such a challenge that it became the focus of several working groups and technical priorities within LinkedIn. Our technical documentation team was often at the center of these initiatives, and the enterprise search team was frequently included as well—so that once we had strong documentation, it would also be easy to find. These groups formed our Development Information team and were tasked with solving our documentation problems. We came up with a three-pronged strategy: improvements in documentation, training, and search.
Our current strategy is to move most documentation into the source code repositories and include it in our code review process to make it easier for engineers to create their own documentation. Our expert writers help the engineers develop this content in a high-quality way. They also assist strategically with documentation for systems that have a high number of dependents or users.
A common problem developers have is finding an answer to a question, and they tend to respond most positively to a Q&A-style program. We chose Confluence Questions as our provider because it integrated well with our existing Confluence wiki. However, with a Q&A-based format, there is a chicken-and-egg problem: you need content to get people to use the system, but you need users to get the content. To seed our solution, we gathered existing FAQ pages from across our organization to add the initial content, totaling more than 900 questions and answers, which was key to driving adoption from the beginning.
Additionally, to help us decide how to prioritize areas that needed fresh documentation, we looked at the demand for information that each area had received. We dispatched technical writers to the teams that were in the most need of documentation overhauls and are working through those projects now.
Documentation is one way to provide on-demand information to developers; however, training is best used to develop fundamental skills through practice under guidance of an expert. LinkedIn has built its own unique set of tools and infrastructure used by engineers that require training. Based on our developers’ needs, we deliver custom classroom or online training for our proprietary technologies. When possible, we use externally available training resources such as LinkedIn Learning for open source or third-party technologies (such as Hadoop). We design our training and documentation to be complementary, where training enables developers to optimally use documentation, in addition to hands-on experience with new systems.
We’ve also begun working with our enterprise search team to make sure that when engineers search for documentation on a particular issue, they find what they need quickly. This creates a virtuous cycle for good documentation: The easier it is to locate, the more it will be used, and the more it is used, the more updated and maintained it will be.
To improve search, we’ve been working with our external search relevance team to find ways to improve internal search relevance. Starting with better relevancy metrics is the key, because we believe that what gets measured gets fixed. After we have automated metrics, we’ll make systematic changes and add features such as user-aware queries. While we make these improvements, we’ll monitor the impact to our metrics and discuss future plans with our partners.
Now that we have the basic pillars in place, we’re in the process of semi-automated archiving of old or inaccurate documentation. We are also creating best practices and templates that documentation partners can leverage. We’re constantly developing and evangelizing new materials to improve our knowledge-sharing culture across our three pillars. If you’re in hypergrowth, get ahead of documentation and training before they become an issue.