目的
当剧本、决策和经验教训以可预测的方式写下来时，分布式团队的行动会更快。本手册概述了我们如何获取知识，以便入职保持顺利，上下文永远不会被困在私信中，事后总结可以作为未来的护栏重复使用。
写作原则
- 清晰第一。 旨在让新团队成员通读一遍就能理解的语言。通过添加澄清性脚注或词汇表条目来打破行话。
- 准确性高于速度。 验证数据、链接和所有者。错误的配置片段比延迟的更新浪费更多的时间。
- 结构简洁。 保持段落简短，首选项目符号列表，并使用标注来表示关键警告或提示。
- 面向受众。 根据目标角色定制文档。协调员指南应突出工具、时间和故障模式，而运行手册应突出命令和回滚步骤。
- 版本化和所有权。 每个页面都列出“更新”日期和负责使其保持最新状态的所有者。
文档生命周期
将文档视为一个与您的SDLC相呼应的持续循环。一个轻量级的文档开发生命周期（DDLC）可以保持内容最新：
graph TD
A[规划] --> B(分析)
B --> C{内容开发}
C --> D[审查和编辑]
D --> E(发布)
E --> F[维护和更新]
F --> A
- 规划： 定义范围、受众和发布渠道。将文档与可衡量的结果配对（例如，减少入职时间）。
- 分析： 采访主题专家，审查指标，并收集屏幕截图或数据导出。
- 内容开发： 使用共享模板起草文档。在流程清晰度很重要的地方使用Mermaid嵌入图表。
- 审查和编辑： 将草稿至少通过一位同行和一位负责任的所有者进行准确性和语调的审查。
- 发布： 通过共享文档站点发布，标记页面以便在搜索和侧边栏导航中显示。
- 维护： 安排季度审查。归档或合并过时的页面以防止知识漂移。
我们技术栈中的工具
- Markdown优先创作： 在VS Code或文档门户中编写，保持格式简单且易于比较。
- 静态发布： Astro + Starlight呈现快速、可搜索的页面，并带有内置导航。
- 图表绘制： 对于架构、工作流程和决策树，首选Mermaid，以便更新保持在版本控制中。
- 版本控制： 所有文档都与代码一起存放在Git中，以重用熟悉的审查工作流程。
推出
- 在团队入职和冲刺回顾期间介绍手册。
- 将标准与运行手册、决策和事件审查的模板配对。
- 跟踪“上手时间”（团队成员需要多长时间才能上手）并在出现摩擦时更新手册。
- 公开庆祝贡献，以便文档工作与发布功能一样受到重视。