- 统一格式（Markdown） 消除了碎片化。
- Git 作为基础 确保了版本控制、审计和协作。
- Docsify + GitLab — 轻量级且快速的解决方案，无需笨重的生成器。
- Discourse 作为“沙盒” — 非常好的想法，用于集体完善想法直到最终发布。
问题：多任务处理下的文档记录
日常任务的忙碌和频繁的任务切换，没有时间进行文档记录。在不断切换于以下内容时，优化其编写的问题被提出：
- CI/CD 管道
- 监控
- 自动化
- R&D
- 支持上述内容
- 支持客户
- 以及详细的时间记录
无法专注于高质量的文档记录。而且我不会以草率的方式完成任务。
需要的是：
- 记录操作
- 用图片、链接和时间戳补充记录
- 避免在同一草稿中混淆不同的主题
- 确保可以在一台计算机上开始工作，然后在另一台计算机（包括移动设备）上继续工作
- 自动保存草稿，以便从任何设备访问
- 轻松恢复未来的工作进度
- 能够在任何阶段分享草稿。
最初的想法是将草稿转化为完整的可用文档，并在项目文档中发布，而无需绑定于时间线的各个阶段。最终找到的方法不仅超出了本地使用的范围，而且成为了组织知识的默认部分，并且在项目中经常将其用作标准。
我构建了一个 灵活、可扩展和以人为本的文档系统 ，它考虑了工程师在高负荷下的工作现实。放弃孤立的草稿而倾向于公开讨论——这是一个特别重要的决定。它不仅加快了文档质量的提升，而且还让团队参与到过程中来。
目标：文档即代码
使用扩展格式创建草稿并像处理软件代码一样处理文档。这带来了一些好处：
- 节省格式化和转换的时间
- 自动生成在线文档
- 离线模式（得益于浏览器缓存），尤其有价值：
- 在客户的封闭网络中
- 在没有互联网连接的区域中。
“客户高度评价了此功能”——我想这样写，但我们在俄罗斯对有用的东西很少发表评论。为了理解该格式是否普及，我只需要一个客户使用缓存页面一年的评估，并试图了解项目团队提到新的图表和文本，而客户并没有看到。当从另一台电脑打开页面时，他们意识到只有他自己才能在没有互联网的情况下打开它。这意味着花在文档上的时间不是白费的。
选择的技术栈
基础是 Markdown 格式，因为它：
- 在 GitLab、YouTrack、某些消息传递应用程序中得到支持
- 所有现代 LLM 都正确识别
- 可以避免 Word 版本问题、“跑偏”的图片和不兼容的格式。
可以直接从草稿中获得：
- 在线版本
- 严格而漂亮的 PDF，风格与在线版本相同。
当前文档实践
今天文档：
- 编写 使用 Markdown 格式
- 存储 在 GitLab 中：
- 所有员工都可以根据角色访问
- 支持多人编辑
- 自动收集 到在线版本：
- 使用 Docsify 容器
- 每分钟更新一次
- 通过 DNS 发布网站（每个项目使用三级或四级名称）
- 导出为 PDF，采用统一的 Vue.js 样式（对网站和文件都相同）
- 图表 创建两种格式：
- Draw.io (outline, 用于复杂的图表)
- Mermaid (inline, 直接在 Markdown 中)
- 导出图表：
- 为 SVG (主要格式)
- 有时为 PNG（用于不兼容的平台）
- 包含图表的原始代码到文件中。
三层文档模型——及其简化
最初，我考虑了三层文档：
- 草稿 — 个人、快速变化的注释。
- 经常更改的文档 — 协作工作材料。
- 静态文档 — 最终、经过验证的版本。
然而，我决定：
- 放弃草稿的匿名性和隔离性，
- 将第一层和第二层合并 到 Discourse 上的通用 Wiki 草稿中
- 将 静态文档 保留在 GitLab + Docsify 中。
尽管第二层和第三层之间 没有自动同步，但我认为这种方法是可行的：它简化了知识流，降低了同事的入门门槛，并加快了从想法到发布的过渡。
工具和格式
| 文本 | Markdown (.md) | 主要编写格式 |
| 存储 | GitLab | 版本控制、评审、按角色访问 |
| 在线发布 | Docsify (在 Docker 容器中) | 从 Git 自动收集网站 |
| 草稿和讨论 | Discourse | 集体完善想法 |
| 嵌入式图表 | Mermaid | Markdown 中的流程图、序列图 |
| 外部图表 | Draw.io (.drawio → .svg) | 复杂的架构图 |
| 导出到 PDF | Docsify + 统一 Vue 样式 | 用于离线访问和传递给客户 |
其他事项
该方案还有改进的空间：
- Discourse 和 GitLab 之间的同步
- 完善评审流程，使其进入准备发布最终版本的状态
- 维护链接完整性
- 自动化发布
- 反馈机制以识别不一致之处以及关于修复的通知。