About SRGTechnical ArticlesRecruitment Information
About SRGTechnical ArticlesRecruitment Information
HOME/Technical Articles/Documentation site for internal developers created with VitePress

Documentation site for internal developers created with VitePress

Suzuki (@sZma5a)is.
#SRG(Service Reliability Group) is a group that mainly provides cross-sectional support for the infrastructure of our media services, improving existing services, launching new ones, and contributing to OSS.
This article isCyberAgent Group SRE Advent Calendar 2025This is the 15th article of the series. In addition to introducing a case study on building a website that centralizes dispersed internal information using esa.io and VitePress, we are also considering using Diátaxis to improve the quality of our documents.

Introduction

We are currently building a documentation site for our internal developers. The goal of this project is to centralize the documentation required for development and provide an environment where developers can quickly access the information they need. In this article, we will introduce the background to the construction of the site, the architecture we adopted, the reasons for the 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-scale operation has yet to begin.

Issues faced

There were two main issues that led us to build this website.
First, documentation was scattered across various locations. Due to historical reasons, internal information was scattered across both esa.io and Notion. This left developers in a situation where they didn't know where to find the information they were looking for.
The second issue was a lack of documentation from a use case perspective. While documentation did exist, much of it was organized by tool or function. When a developer wanted to do something, they would often have to read multiple documents to complete the task. To access the appropriate information, they needed to have a comprehensive understanding of the system and documentation beforehand, which could be difficult for new team members to keep up with.
To solve these two issues, we need to create a place and structure that allows users to quickly access the information they need, and we are considering providing a documentation site and introducing Diátaxis.

System Architecture

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

Data sync from esa.io

The master data for the content to be posted on the site is stored in esa.io. GitHub Actions are used to call the esa.io API on a daily schedule. Documents under specific directories or with specific tags are retrieved, including not only the text but also images, and converted into Markdown format that can be used by VitePress before being saved in the repository. This means that if a document is updated on esa.io, it is automatically reflected on the site the next day.

Hosting and security with Cloudflare Pages and Zero Trust

The generated static site is hosted on Cloudflare Pages. We chose Cloudflare Pages because it's easy to build in conjunction with a GitHub repository and because a preview URL is issued for each pull request, making it easy to check.
Additionally, since it is an internal site, it is essential to restrict access from outside, and for this purpose Cloudflare Zero Trust is used. By utilizing the Cloudflare Zero Trust environment that had already been implemented within the company, it was easy to create a secure environment where only authenticated users could access the site.

Search function

To improve information retrieval, we utilize VitePress' standard full-text search function, which allows for cross-sectional searches of documents on the site. While the standard function is sufficient at the moment, we have designed the system so that we can consider introducing external search services such as Algolia if search requirements become more advanced in the future.

Technology selection

Backstage, developed by Spotify, is a well-known choice for building internal developer portals (IDPs) and documentation sites. However, this time we chose VitePress instead of Backstage.
The main reason for this was that we decided that Backstage was overkill for our purposes. Backstage offers powerful features for managing the entire development lifecycle, such as a service catalog, software templates, and a rich plug-in mechanism. However, the main objective of this project was to "consolidate documentation and make it easier to view."
VitePress is a static site generator based on Vue.js, and is extremely lightweight and fast. It is specifically designed for use as a documentation site, as it allows for simple document management and writing using Markdown. Its ability to provide a fast browsing experience while keeping construction and maintenance costs low made it ideal for our requirements.

Content Design

Simply consolidating documents does not solve the fundamental problems of "not knowing what to write" and "it's difficult to read." Therefore, we are considering adopting the "Diátaxis" framework as a guideline for document organization.
Diátaxis is an approach that categorizes documents into four types based on user needs:
  • Tutorials: Learning-oriented. Hands-on lessons.
  • How-to Guides: Problem-solving oriented. Steps to complete a specific task.
  • Reference: Information-oriented, with detailed technical specifications and parameter descriptions.
  • Explanation: Understanding-oriented. Explanation of background, concepts, design philosophy, etc.
Previously, information was organized by tool, which tended to mix use cases (how-to) and specifications (reference). By adhering to Diátaxis, authors can clearly see what to write and where, and readers can quickly find information that suits their purpose. Several external tech blogs have also reported on its adoption, and it is considered effective in improving the quality of documentation.

Conclusion

Currently, the construction of the site itself is complete, and we are in the process of examining the content. Operational aspects such as formulating operational rules for the Diátaxis framework are yet to be worked out. It is important that documentation is not something that is "written and finished," but that it is continually maintained and utilized. We will continue to build an environment where developers can easily access information.
SRG is looking for people to work with us.
If you are interested, please contact us here.