一、把技术文章当作可复现实验
高质量技术文章不是“把知道的内容写长”，而是让读者在明确前提下复现结果、识别失败并安全回滚。本文给出一套从选题、实验环境、命令证据、截图、审校到长期维护的完整工作流，适用于教程、故障复盘、性能评测和架构实践。
真实问题 -> 明确读者与完成标准 -> 隔离实验
-> 逐步执行与保存证据 -> 解释原理和失败
-> 独立复测 -> 编辑审校 -> 发布
-> 版本监控 -> 勘误与更新
二、先写读者、前提和完成标准
开始前用一页简报回答：谁会读、读者已有能力、要解决什么、明确不解决什么、完成后如何验证。模糊题目“学习 Kubernetes”应收敛为“在三节点集群部署某组件，并通过固定检查确认高可用”。
title: PostgreSQL 逻辑复制零停机迁移
reader: 熟悉 SQL、第一次实施跨集群迁移的运维工程师
prerequisites:
- 两套隔离 PostgreSQL 18 实例
- 可执行 pg_dump 和 psql
- 维护窗口与回滚负责人
success:
- 初始同步完成
- 停写后关键表摘要一致
- 应用切换后错误率与延迟达标
out_of_scope:
- 双主冲突合并
- 未经演练的跨地域灾备
完成标准必须可测，不能写“运行正常”“性能较好”。
三、使用可销毁实验环境
把文章中的系统搭在专用虚拟机、容器或测试集群中。记录 OS、内核、CPU 架构、软件版本、镜像 digest、配置哈希和时间。不要直接在生产边试边写。
date -Is
uname -a
cat /etc/os-release
docker version
docker compose version
docker image inspect postgres:18 \
--format '{{index .RepoDigests 0}}'
sha256sum compose.yaml configs/* | tee evidence/config-sha256.txt
evidence/
environment.txt
config-sha256.txt
commands.log
stdout/
screenshots/
metrics/
acceptance.md
实验数据应为合成或脱敏数据，证据目录不能包含 Token、真实域名私钥、Cookie 或个人信息。
四、设计最小实验矩阵
文章不能只覆盖成功路径。至少定义正常、边界、失败、恢复四类场景，并为每个场景写输入、预期、观察点与清理步骤。
| 场景 | 输入 | 预期 | 证据 | | --- | --- | --- | --- | | 正常 | 合法配置与请求 | 2xx、数据一致 | 响应、日志、查询 | | 边界 | 空数据/最大长度 | 明确处理 | 状态码、验证信息 | | 失败 | 断网/错误凭据 | 有界失败 | 超时、错误码、告警 | | 恢复 | 依赖恢复 | 自动或手动恢复 | 指标回落、状态转换 |
mkdir -p evidence/{stdout,screenshots,metrics}
script -q evidence/commands.log
# 执行实验；结束时输入 exit
五、把每一步写成“目的—命令—结果—解释”
命令前后都要消除猜测
命令前说明目的和影响，命令后给出关键预期，不要贴一大段终端却不解释。示例中的变量、主机名和文件路径要统一。
# 目的：确认服务真正从新配置启动
sudo systemctl daemon-reload
sudo systemctl restart report-api
systemctl show report-api -p ActiveState -p MainPID -p FragmentPath
预期：ActiveState=active、MainPID 非 0、FragmentPath 指向本文创建的 unit。若失败，先运行 journalctl -u report-api -b -n 100，不要继续执行后续步骤。
危险命令必须给出精确范围、备份和回滚；不要用未经解释的 curl | sh、rm -rf、关闭防火墙或全局 chmod 777。
六、配置文件必须完整且可定位
零散片段容易让新手把配置放错层级。先给完整最小配置，再单独解释关键字段；若只展示差异，明确基准文件和插入位置。
services:
db:
image: postgres:18
environment:
POSTGRES_DB: lab
POSTGRES_USER: lab
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets: [db_password]
healthcheck:
test: [CMD-SHELL, "pg_isready -U lab -d lab"]
interval: 5s
timeout: 3s
retries: 20
secrets:
db_password:
file: ./secrets/db_password.txt
解释时关注安全和运行语义：密码通过文件注入；healthcheck 判断就绪而非仅进程存在；镜像版本应进一步固定 digest。
七、架构图表达数据流和信任边界
图必须回答的问题
架构图要回答组件、方向、协议、状态和边界，不追求装饰。正文中先给逻辑图，再在关键步骤给时序或故障路径。
[User]
| HTTPS
v
[Gateway] --trace_id--> [API] --SQL/TLS--> [Database]
| |
| metrics `--event--> [Queue]
v
[Monitoring]
Trust boundaries: Internet | Cluster Edge | Application | Data
图中的名称必须和命令、配置一致；如果图写 catalog-api，示例不要突然改成 backend。
八、截图只证明视觉事实
截图适合证明页面布局、图表趋势和 GUI 设置，不适合代替可复制的命令与配置。截图需裁掉账号、书签、Token、内网地址，并配时间、版本和说明。
exiftool -all= screenshot.png
pngcheck -v screenshot.png
sha256sum screenshot.png >> evidence/assets.sha256
不要重复放“封面图 + 正文第一张相同大图”。文章缩略图负责列表识别，正文图只在确实帮助理解时出现。
九、验证事实与官方资料
对版本、默认值、弃用项和安全行为优先引用官方文档、规范或源代码。文章应标明验证日期和实际版本。搜索到的二手文章可以帮助发现问题，但不能替代权威依据。
Claim: PostgreSQL logical replication does not replicate schema definitions.
Primary source: PostgreSQL 18 / Logical Replication / Subscription.
Local proof: target created without schema -> subscription table sync fails.
Article action: add schema-only migration before CREATE SUBSCRIPTION.
引用不要集中成“官方资料”列表后就结束；关键限制应在对应步骤附近解释，文末再汇总入口。
十、让另一人按文档独立复测
作者知道隐含前提，容易自动补齐缺失步骤。让未参与写作的人从空环境执行，禁止口头提示，只记录卡点、错误指纹和耗时。
- TEST-ID: DOC-POSTGRES-001
- clean environment: yes
- first failure step: 6
- observed: subscriber missing schema
- expected: schema restored before subscription
- evidence: evidence/stdout/step-06.txt
- status: FAIL
修正文章后必须从失败步骤的前置状态重新验证；仅修改文字而不复测，不能宣称通过。
十一、结构与排版规范
页面标题由站点 H1 呈现，正文从 H2 开始；H3 只用于 H2 下的子问题。每段聚焦一个观点，列表用于并列项，表格用于精确映射，代码块注明语言。不要用加粗句子伪装标题。
H1 页面标题（站点生成）
H2 目标与前提
H2 架构
H2 实施
H3 步骤 A
H3 步骤 B
H2 验证
H2 排障与回滚
H2 官方资料
首次出现的缩写要解释。中文与英文术语之间保持一致空格规则；同一对象只用一个译名。代码行太长时通过变量或换行改善，不靠横向滚动让读者猜。
十二、安全与可复制性审校
发布前的自动检查
发布前执行秘密扫描，检查示例是否包含真实凭据、危险默认、过度权限和不可逆命令。
rg -n '(password|token|secret|api[_-]?key)\s*[:=]' article.md evidence/
rg -n 'chmod 777|--privileged|curl.+\|.+sh|rm -rf' article.md
shellcheck scripts/*.sh
docker compose config --quiet
所有占位值使用明显格式，如 REPLACE_ME、example.com、RFC 保留网段。不要伪造“命令成功”的输出；无法实际验证的内容明确标为假设或待验证。
十三、发布清单与版本维护
发布前确认：标题准确；摘要说明收益与边界；前提完整；命令从干净环境可执行；配置完整；所有危险操作有警告与回滚；图片不重复；链接可访问；版本和日期明确；无秘密。
article_maintenance:
verified_at: 2026-09-28
verified_versions:
product: "18.x"
os: "Ubuntu 24.04"
review_triggers:
- upstream major release
- security advisory
- reader reproduction failure
owner: platform-docs
更新时保留变更记录：改了什么、为什么、重新验证了哪些步骤。旧版本仍有大量用户时，单独维护版本分支，不要悄悄把命令替换成不兼容的新语法。
十四、质量验收
一篇可发布教程至少做到：读者前提清楚；环境可重建；每一步有目的、命令和预期；失败有定位路径；关键结论有官方资料与本地证据；安全边界明确；另一人独立复测通过；发布后有维护责任人。
真正的“详细”不是重复结论，而是消除读者必须猜测的地方。只要某一步仍需要作者在旁边解释，它就还不是可交付的操作文档。