About SRGTechnical articleRecruitment Information
About SRGTechnical articleRecruitment Information
HOME/Technical article/Creating an internal developer documentation site with VitePress

Creating an internal developer documentation site with VitePress

Suzuki from the Service Reliability Group (SRG) of the Media Management Division@sZma5a)is.
#SRGThe Service Reliability Group primarily provides comprehensive support for the infrastructure surrounding our media services, focusing on improving existing services, launching new ones, and contributing to open-source software (OSS).
This article is aboutCyberAgent Group SRE Advent Calendar 2025This is the 15th article in this series. In addition to building a site that centralizes dispersed internal company information using esa.io and VitePress, this article introduces our consideration of using Diátaxis to improve document quality.

Introduction

We are currently building a documentation site for our internal developers. The goal of this project is to centralize the documentation necessary for development and provide developers with an environment where they can quickly access the information they need. This article will introduce the background to the site's construction, the architecture we adopted, the reasons for our technology selection, and our efforts to improve the quality of the documentation. Please note that this site is currently in the construction and planning stages, and full operation will begin in the future.

The challenges they faced

There were two main challenges that led us to decide to build this website.
The first issue was that documentation was scattered across various locations. Due to historical reasons, internal information was scattered across both esa.io and Notion. As a result, developers were in a situation where they didn't know where to find the information they were looking for.
The second issue was the lack of use-case-centric documentation. While documentation existed, much of it was organized by tool or feature. When a developer wanted to do something, they often had to read through multiple documents to complete the task. Accessing the right information required a prior understanding of the overall system and documentation, which could be particularly difficult for new team members to catch up on.
To address these two challenges, we need to create a place and configuration that allows users to quickly access the information they need, and we are considering providing a documentation site and implementing Diátaxis.

System Architecture

The site we have built will consolidate the knowledge accumulated on esa.io and provide it in an easy-to-view format. The overall architecture is as follows:

Data synchronization from esa.io

The master data for the content to be published on the site is located at esa.io. We use GitHub Actions to call the esa.io API once a day. We retrieve not only the text but also images from documents in specific directories or with specific tags, convert them to Markdown format that can be handled by VitePress, and save them to the repository. This ensures that if a document is updated on esa.io, it will be automatically reflected on the site the next day.

Cloudflare Pages and Zero Trust hosting and security

The generated static site is hosted on Cloudflare Pages. We chose Cloudflare Pages because it allows for easy setup by integrating with GitHub repositories, and because a preview URL is issued for each pull request, making verification easy.
Furthermore, since this is an internal site, restricting external access is essential, and we utilize Cloudflare Zero Trust for this purpose. By leveraging the Cloudflare Zero Trust environment that was already in place within the company, we were able to easily create a secure environment where only authenticated users can access the site.

Search function

To improve the ease of finding information, we utilize VitePress's standard full-text search function. This allows for cross-document searches within the site. While the standard function is sufficient at present, the configuration is designed to allow for the introduction of external search services such as Algolia if search requirements become more sophisticated in the future.

Technology selection

Backstage, developed by Spotify, is a very well-known choice for building internal developer portals (IDPs) and documentation sites. However, this time we deliberately chose VitePress instead of Backstage.
The main reason is that we determined Backstage was overkill for our objectives. Backstage has powerful features for managing the entire development lifecycle, such as a service catalog, software templates, and a rich plugin mechanism. On the other hand, the main objective of this project was simply to "centralize and make documentation easier to view."
VitePress is a Vue.js-based static site generator that is extremely lightweight and fast. Its simple Markdown-based document management and writing capabilities make it ideally suited for documentation sites. Its ability to provide a fast browsing experience while keeping construction and maintenance costs low made it perfectly suited to our requirements.

Content design

Simply consolidating documents won't solve the fundamental problems of "not knowing what to write" or "difficulty reading." Therefore, we are considering adopting the "Diataxis" framework as a guideline for document structure.
Diátaxis is an approach that categorizes documents into the following four types based on user needs:
  • TutorialsLearning-oriented. Lessons involve hands-on learning.
  • How-to GuidesProblem-solving oriented. A set of steps for completing a specific task.
  • ReferenceInformation-oriented. Detailed technical specifications and parameter descriptions.
  • ExplanationUnderstanding-oriented approach. Explanation of background, concepts, design philosophy, etc.
Previously, information was organized on a per-tool basis, often resulting in a mix of use cases (how-to) and specifications (reference). By adhering to Diátaxis, writers gain clarity on "what to write and where," and readers can quickly find information that suits their needs. Several external tech blogs have reported on its implementation, and it is considered effective in improving the quality of documentation.

In conclusion

Currently, the site itself is complete, and we are in the stage of reviewing the content. Operational aspects, such as establishing operating rules for the Diátaxis framework, will be addressed from now on. Documentation is not something that is "written and done," but rather something that is continuously maintained and utilized. We will continue to build an environment in which developers can easily obtain information.
SRG is looking for new team members.
If you are interested, please contact us here.