How to start integrating docs-as-code culture using in-house dev platform

I had the opportunity to work on a project with a blank slate after joining the company six months ago. This presented me with numerous possibilities for implementing creative solutions. However, for the project to succeed, we had to comprehend the expectations from docs and determine an approach and docs tools.

Hello! My name is Anna Goncharova, I am a senior technical writer at inDrive. Collaborating with the Documentary team, which includes a backend engineer, a frontend engineer, and myself, we are developing a dev platform using the docs-as-culture approach. We aim to enhance engineering productivity throughout the tech division.

This article presents the model we aim to achieve, as we are still in the early stages of integrating our documentation culture initiative. We aim to solve a common issue encountered by growing startup companies, which involves organizing and updating technical information across the tech division and its development teams.

Background

Although the challenges of docs in a growing startup are generally consistent, the adoption of a documentation culture can vary between companies. Each approach has pros and cons, and it is crucial to select the one most suitable for a company’s docs requirements and processes.

Before cultivating an engineering documenting culture, one must first undertake key steps:

• survey the engineers’ docs expectations;
• analyze the current docs volume and subject matter;
• choose an appropriate tool and format.

Based on that, our Documentary team developed an in-house platform named the Documentary Platform, which renders data from our repos and serves as a single source of truth for our developers searching for valid information. We also opted for the docs-as-code approach, where docs written in markup language are updated alongside the code as app development progresses. GitHub is used for docs management and version control. For docs writing, we use Markdown, which we selected between two options, Markdown and Asciidoc, because some developers had already written Readmes in their repos using Markdown.

Getting started pages of the Documentary Platform

Design and development of the dev platform

The fundamental concepts of a dev platform were conceived and brought to life by a group of inDrive developers during a company-organized Hackathon.

We don’t have any fancy stuff or complicated systems on the backend yet. We’re using Go for the backend, MongoDB to store our data, and GraphQL as an API. Our main data source is GitHub, so we’re actively using the GitHub API. To parse and render Markdown files, we use the Goldmark extensible library, which gives us complete control over the process. We even wrote our tree renderer in JSON to draw on the front.

For our frontend, we use React and communicate with the backend via GraphQL using Apollo. We create contracts based on a final GraphQL diagram on the backend. The routing is implemented using react-router-dom, and we do not use a state manager. Our UI kit is based on the inDrive Oymyakon design system. To render content, we use self-written solutions and open-source libraries, including swagger-ui-react, mermaid, slack-markdown, and graphql-voyager. Our building tools and development process rely on WebPack, eslint, husky, and prettier.

The basic features below were enough to launch the first version of the platform for preliminary selected earlier adopters:

• Repo connection to the platform.
• Parsing of Markdown files and support for all basic Markdown elements.
• Doc structuring from Markdown files.
• Rendering of API (Swagger).
• Platform data search functionality.
• Rendering of the repo owner’s data.

To ensure ease of use for all users in our tech division, the platform has been designed with simplicity. As a result, only two basic service files have been developed to facilitate quick and easy setup:

• documentary.toml — a mandatory TOML file is located in repo root, containing relevant repository values for each field. The screenshot below displays all possible fields that can be specified in this file:

.documentary.toml

Once the .documentary.toml file has been added to the main branch of a repo, it is possible to connect the repo by clicking on a connection button of the platform interface. This is how the data from the documentary.toml file is rendered on the platform after the connection:

Rendering of service info

documentary.toml file is constantly under development. New fields are added if teams need to render new data on the platform. For example, recently we added two areas for metrics and logs.

• TOC.yaml is an optional file that can help structure docs from Markdown files in a repo. An example of the file’s structure can be seen below:

TOC.yaml

The final rendering of the specified structure on the dev platform:

Final rendering of doc structure

Launch of the dev platform

The Documentary Platform became available to early adopters six months after the development began and was stabilized for use. Before the launch of the Documentary Platform, several important actions were taken to ensure a smooth user experience:

• We identified early adopters among the tech division engineers who were willing to invest their time in trying out the platform for docs writing.
• To assist users in getting started with the Documentary Platform, we developed initial guides covering various topics, such as a quick start guide, writing style guide, Markdown guidelines, and the docs-as-code approach. These guides are accessible through a link on the platform’s getting started page. In addition, the Documentary Platform’s docs were an example for other users to follow.
• A getting started workshop was held one day before the launch. We worked with the first users to execute the repo connection process to the platform and demonstrated the basic principles of working with docs using the platform. The docs and processes were presented in a step-by-step format to facilitate understanding and adoption of the documentation culture alongside the development platform.
• We created a Slack channel for users to communicate with the Documentary team and promptly address any issues or questions. The initial users’ feedback and assistance helped us resolve the first issues and stabilize the platform. We continue developing the platform by adding new features based on user feedback and the evolving documentation culture.

Start of docs-as-code integration

The Documentary Platform stabilization process was ongoing when we began working on tech docs. However, it was also necessary to initiate the documenting workflow.

Currently, the basic process of working with the team looks as follows, although it may vary depending on the team’s workflow:

Docs workflow

The basic workflow includes the following stages:

• documenting (contribution to a repo):
• new features: documenting newly developed features and merging to the main default branch at feature release;
• general improvements: typo corrections, error fixes, and better explanations through clearer writing and examples.
• review and address comments and feedback;
• release (publication on the Documentary Platform).

Participants of the flow:

• contributors — devs or tech writers;
• reviewers — devs or tech writers.

The exact contributors and reviewers are assigned and agreed upon by the teams. Each repo describes The contribution process in a “Contributing” document.

Initial development of tech docs can be complex and time-consuming for engineers, especially when they are already heavily involved in coding. One big challenge we faced was validating and migrating data from various sources to the platform. To address this, we allocate time every quarter for docs development as part of the engineers’ tech investments initiative, which aligns with our company’s OKR culture. I gather information about the product or service and create a doc structure to make things easier for the dev teams. If there’s not enough info, I create a task for an engineer to add the missing data to the repo. This helps speed up the documentation process and doesn’t block the docs writing start.

During this stage, close communication with the teams and the engineers assigned to docs tasks was crucial to ensure that the teammates understood how to work with the docs and the platform. For this reason, introductory workshops were conducted during the communication phase.

Once connected to the platform, the docs will be updated regularly as new features are developed. By following these processes and strategies, we have streamlined our docs development process and ensured that our engineers can focus on their core responsibilities while still delivering docs updates.

So, at the current stage, the technical writer:

• Initiates the development of the structure of the docs.
• Reviews PRs with changes to the docs. A PR is automatically assigned to the technical writer listed in the CODEOWNERS file in a repo.
• Consults with colleagues on any issues related to working with docs and the Documentary Platform, and conduct webinars and workshops on documenting culture.

During the development process, teams must remember to update the docs. I periodically track new tasks and act as a pusher with suggestions on which info could be included in the docs. After several reminders, the teams understand what information should be documented regularly.

Regarding implementing the docs-as-code approach, engineers must participate in writing the docs. Therefore, triggers for when docs need to be updated within a specific task should be more systematic. At this stage, a non-intrusive approach to control is important. Yes, docs should be up-to-date, but synchronous actualization is achieved gradually and, at this stage, through the following methods that we are working on:

• The Team Maturity Model in our tech division also identifies the critical areas for improving maturity in maintaining up-to-date tech docs in sync with code changes using the Documentary Platform. It is also essential for teams to take responsibility for keeping docs as part of their product development, with the technical writer’s role becoming more consultative over time. This is crucial, as increasing the number of technical writers to expand the volume of supported docs is not a viable solution at our company.
• Developing guidelines and checklists that will form the basis for incorporating docs checks into the CI/CD is another crucial step. A checklist includes a list of files in a repo that are affected by changes made to the code base. If a dev team experiences difficulties keeping the docs up-to-date while prioritizing development speed over quality and docs, a technical debt task is created.

However, it should be noted that this approach does not work when docs are published for external users (such as user guides and, especially, APIs), and the docs must be posted strictly alongside the release of functionality.

Challenges faced and addressed

While there are undoubtedly positive outcomes of this approach, there are also several challenges that we have faced at this stage:

• The difficulty for non-engineers colleagues to work with Markdown and developer tools for docs.
• Platform immaturity at the initial stage and need for functionality for those used to working with tools such as Notion and Confluence.
• Lack of time and competing priorities for the business prevents teams from fully dedicating themselves to their docs and refining them.

Since we deliberately chose to work exclusively with tech docs in Documentary Platform, it has become the primary tool for docs management and process building. To address any challenges that arise, we have implemented the following measures:

• Close collaboration with each team at the very beginning of work with the platform;
• Swift response to any platform issues reported by the engineers;
• Analysis and implementation of the most requested features to smooth user experience;
• Assistance with the initial organization and ongoing curation of docs processes.

What’s next

We are continuously developing the Documentary Platform by adding features that support the docs-as-code approach and responding to our users’ requests. For example, we are currently working on implementing version control for docs and data from feature branches and adding commenting and an embedded Markdown editor. Furthermore, we are incorporating ChatGPT into our documentation process to increase engineering productivity. Automated guidelines are also critical to developing the docs-as-code approach within development teams.

We will continue to share updates on our documentation culture development progress at inDrive, so stay tuned!