写给每一个 openEuler 贡献者：文档不是“附属品”，是第一生产力

作者：Echo_Wish

说句掏心窝子的话：在很多技术团队里，“写文档”这事儿经常被当成是“可有可无”、“最后再补”、“反正代码都能跑”的那种工作。但你去 openEuler 社区走一圈就会发现——文档不是锦上添花，而是地基和路标。
没有文档，项目可以写得很炫，但没有人用；有了好文档，哪怕功能还不够完美，也能吸引人来参与。

为什么 openEuler 如此强调文档？我们今天就来聊聊 openEuler 的文档标准、内容组织、工具链体系、实践落地方法，以及——如何写出让人“看得懂、用得上、愿意贡献”的文档。

一、文档并不是“描述代码”，是构建知识的入口

我见过这样的文档：“本模块实现 A 功能，调用 B 接口，见代码”。
讲真，这不是文档，这是复读。

文档的核心使命有三个：

一句话总结：
文档写的是思路、标准、结果与使用行为，而不是“解释代码长得啥样”。

二、openEuler 文档的结构标准（这是硬规则）

openEuler 推荐文档采用 信息分层结构：

/docs
 ├─ quick-start      # 最快上手
 ├─ user-guide       # 使用指南
 ├─ developer-guide  # 开发与参与文档
 ├─ design           # 设计细节与演进记录
 └─ release-notes    # 版本变更记录

这个结构为什么重要？

• 新手需要 Quick Start → 先能跑，再理解
• 开发者需要 Developer Guide → 按模块入口贡献代码
• 内核/组件演进需要 Design Notes → 记录技术决策与背景脉络
• 商业用户需要 Release Notes → 知道版本差异与风险点

写文档，就是把知识给不同角色“按需交付”。

三、文档格式与工具链：Markdown + Sphinx + RST + CI

openEuler 的文档并不是“随便写写 Markdown”就能合上去的，它有一套成熟的构建链：

示例：openEuler 文档构建流程

# 克隆文档仓库
git clone https://gitee.com/openeuler/docs.git
cd docs

# 安装依赖并构建
pip install -r requirements.txt
make html

# 输出目录
build/html/index.html

这里最关键的是：文档和代码一样，必须可构建、可审查、可发布。

文档不是 wiki，它是版本化的资产。

文档写作规范（重点！）

例子说明下：

❌ 不合格写法

安装服务即可使用。

✅ openEuler 推荐写法

# 安装软件包
sudo dnf install my-service

# 启动服务
sudo systemctl enable --now my-service

# 验证运行状态
systemctl status my-service

文字描述要配合 可复现的命令与预期结果，这样用户才能预期一致地操作。

四、如何写出“别人愿意看、愿意用、愿意贡献”的文档

我从 openEuler 文档组里总结过一句话：

文档不是告诉用户“应该怎么做”，而是帮助用户“不被卡住”。

所以写文档的核心点只有三个：

来看一个 清晰可用的模块边界示例：

+-------------------------+
|  MyService Application  |
+--------------+----------+
               |
+--------------v----------+
|  myservice-api (REST)   |
+--------------+----------+
               |
+--------------v----------+
|  myservice-core logic   |
+--------------+----------+
               |
+--------------v----------+
|  openEuler system libs  |
+-------------------------+

你会发现，这比“看源码自动理解”高效太多。

五、实战案例：把“抽象说明”改成“上手可跑”

假设我们要写一个服务的安装文档

原始写法（90% 的文档都这么写）

本服务依赖 PostgreSQL 数据库，请提前安装。

改进写法（openEuler 官方风格）

# 安装 PostgreSQL
sudo dnf install postgresql-server

# 初始化数据库
sudo postgresql-setup --initdb

# 启动并设置开机自启
sudo systemctl enable --now postgresql

# 设置数据库账号
sudo -u postgres psql -c "CREATE USER appuser WITH PASSWORD '123456';"
sudo -u postgres psql -c "CREATE DATABASE appdb OWNER appuser;"

echo "✅ 数据库安装与初始化完成"

一个区别：
前者让用户自己查
后者让用户两分钟跑起来

这就是文档的价值。

六、Echo_Wish 的温度思考

我一直相信一句话：

开源不是代码合作，开源是知识共同体。
文档，是知识共同体的语言。

写文档不是“给别人看”，
写文档是
让自己三个月后也能重新理解自己的代码。

写文档不是“浪费时间”，
写文档是
减少沟通成本、维护成本和认知成本的最高 ROI 投资。