When documentation is difficult to locate, it’s a near-guarantee few (if any) will use it. Last year, we devised a plan to bring documentation into immediate accessibility to all tech team members. To accommodate the already existing documentation and the documentation that was to come, we decided to build an intranet.
We’re a global organization, so we’re not always going to get answers immediately. Sometimes answers to questions can be delayed by a 12-hour time difference, and we work quickly, so the intranet is our 24-hour information space. The intranet breaks up potential information silos by giving team members open and immediate access to our documentation.
Designing the Documentation System
We wanted our new internal documentation system to be centralized - all documentation would be accessible from one place. To meet this requirement, we built one website that all members of DISQOTECH (our engineering department) could access. While crafting this new system, we came up with the goals of our platform: transparency, improved communication, and lower barriers to entry.
Transparency
With transparency, our aim is to give everyone equal access to DISQOTECH concepts, terminology, and API documentation. Transparency means that there are no information silos. No members of the team will have to go hunting around for answers or find the exact person they need to speak with to obtain specific information.
Improved Communication
Our next goal with the documentation system is to improve communication. We want to allow all DISQOTECH members to learn and discuss concepts and terms they’ve learned on our intranet. The concept fits in nicely with our aim of transparency. We are determining that with improved transparency, we can arm tech team members with more information that enables them to have more productive conversations with team members.
Lower Barriers to Entry
The final goal of the documentation system is to give DISQOTECH members a centralized place to access data. Centralizing the documentation will decrease the ramp-up period of new team members. It also enables team members to quickly become acquainted with information about other projects, products, and teams.
One not-so-secret goal of the intranet is also to have a clean, simple interface and consolidated documentation to improve documentation culture within the organization. The more team members interact with the intranet, the more likely they are to remember to document when they’re building new products or updating existing products.
Several teams so far have also added documenting to their Definition of Done. This means that a product is not considered finished until it has some documentation published to our intranet site.
Building the System and Docs as Code
It’s no longer adequate for documentation to be separate from code when the subject of the documentation is technical. Docs as code is a concept in the Technical Writing community that promotes treating documentation as you would code.
For our tech team, this looks like writing documentation directly into a code editor. And more than this, the code goes through version control, in our case, GitLab. When we treat documentation as code, we can track the history of our documentation.
Traditionally, a Technical Writer would produce documentation in a word document, and if the documentation appeared on a website, an engineer would add the content. “Docs as code” shortens the time between writing and publishing, and expects Technical Writers to have some entry-level web development skills.
This snapshot of our internal documentation website shows the front page organization.
Our internal documentation system also enables engineers themselves to edit their documentation. With this, each of our tech team members has agency over the information we put out about a product. The documentation for a given project lives in that project’s repository, so repository members can make quick edits as their software product evolves.
Documentation stored in repositories corresponding to a project is automatically updated through webhooks. Gitlab enables easy set up of webhooks, and we provide thorough instructions, allowing the teams to complete their integration. The documentation itself is hosted on the centralized documentation platform, allowing for unified access to content stored across many repositories.
Types of Content on Our Intranet
DISQO has many different products, including APIs and other types of software and systems. Also, our documentation system needs to accommodate for other kinds of information. Some of the content we now have on our DISQOTECH intranet follows:
Team pages: DISQO currently has 13 teams, all working on different products, but interdependent. The team pages include a list of team members, products and projects, technologies used, team design and development philosophies, coding standards, and more.
Career-specific information: Our tech team has various performance measures that enable members to perform to their fullest potential. On our intranet, we list our career growth framework, vacation policy, and OKR (Objective and Key Result) information.
Business growth information: Our intranet holds a list of all adopted RFCs (Request for Comments), which are turned into action items and new department-wide protocols. In addition, it contains tools such as product inventory management.
These are just some of the content types we house on our intranet. Since we built our system, it’s highly adaptable and accommodates for any new types of content that we want to include.
Overall, the intranet enables us to build a more robust documentation culture, in which we value documentation and contribute to it as part of the build process.
We’re currently hiring global. If you are interested in joining us, please check out our open positions.