>- **Markdown 格式统一化** 消除了碎片化。 >- **Git 为基础** 提供版本控制、审计和协作。 >- **Docsify + GitLab** —轻量快速，无需繁重的生成器。 >- **Discourse 作为“沙盒”**——很棒的想法用于集体讨论到最终发布前的细节.**幼年者站在桌前，身后是无数屏幕显示代码，而电脑却冒出一股烟雾。（AI 为图片提供的标题）|690x394
https://upload.wikimedia.org/wikipedia/commons/7/7a/A_teenage_man_seated_at_a_table_with_many_screens_showing_code,_with_smoke_issuing_from_the_computer (Подпись)
文档化在高强度工作中的挑战
忙碌完成日常任务、频繁跳过紧急事务，没有时间对其进行文档。文档的优化写作方式在团队成员之间经常被提出——主要是在不断切换的背景下：
- CI/CD 管道
- 监控
- 自动化
- R&D（研发）
- 上述内容的支持
- 客户支持
- 并精确记录时间
没有任何时间可以专注于写文档。而且我也不会做得马虎.
所需的是：
- 日志操作
- 添加图片、链接和时间戳
- 避免在同一份草稿中混杂不同主题
- 可以从一个设备开始，再继续在另一个设备上进行，包括移动设备
- 自动保存草稿以便随时访问
- 方便回顾工作进度未来
- 在任何阶段都能共享草稿.
最初的想法是把草稿转化为完整的工作文档并在项目文档中发布，而不受时间线阶段的限制。最终发现的方式让我超越了本地使用，并成为知识库共同的一部分，很多项目甚至将其视作标准.
目标：文档化如代码
创建草稿并以扩展格式编写文档，像与软件代码一样处理文档。这带来了多个优势：
- 节省时间 在格式化和转换上
- 自动生成在线文档
- 离线模式（通过浏览器缓存）——尤为重要的是：
- 在客户的封闭网络中
- 没有互联网的地区
"客户对此功能表示赞许“—我想写这句话，但我们俄罗斯的人在价值上看起来不太情绪化。要理解它已经深入人心，我只需得到一个客户的评估——他一年使用过缓存页面并尝试了解项目中提到的新方案和文字，而这位客户从未看到过这些内容。而当时打开另一台电脑后才发现，没有互联网的情况下它除了他自己之外几乎无法在任何设备上打开——因此证明文档的时间投入是值得的.
采用的技术栈
最终基于 Markdown 的格式，因为它：
- 在 GitLab、YouTrack、一些聊天工具中支持
- 被所有现代 LLMs 正确识别
- 避免了 Word、“卡”了图片以及不兼容的格式带来的问题。
从草稿直接得到：
- 在线版本
- 严谨且美观的 PDF（基于 Vue.js 统一风格），与网页版风格相同.
当前的文档化实践
今天的文档写作是：
- 采用 Markdown 格式
- 存储在 GitLab 中：
- 对所有员工基于角色的访问
- 支持多人协同编辑
- 自动收集生成在线版本:
- 使用 Docsify
- 每分钟更新一次
- 通过 DNS（3 级或更高域名）发布到互联网上
- 导出为 PDF 并统一风格（基于 Vue.js），与网页版一致.
- 绘制图表：
- Draw.io（结构化的、用于复杂图形）
- Mermaid（直接在 Markdown 中嵌入，用于流程图）
- 导出图表格式：
- SVG（主格式）
- 有时 PNG（对不兼容平台）
- 包括绘图源代码内嵌文件.
三层级文档结构及其简化
最初我考虑了三个等级的文档：
- 草稿——个人、快速修改的笔记。
- 频繁变动的工作文档——协作共享材料。
- 静态文档——经过验证并最终的版本。
然而我决定：
- 放弃匿名与孤立的草稿，
- 将第 1 层和 2 层合并为基于 Discourse 的共享 Wiki-草稿，
- 保留静态文档在 GitLab + Docsify 中.
虽然二级（常变动）和三级（静止）之间没有自动同步，我认为这种方式生存可行：它简化了知识流、降低了同事们的入口门槛，并加速了从概念到发布的过程.
工具与格式
| 文本 | Markdown (.md) | 主要写作格式 |
| 存储 | GitLab | 版本控制、审阅、角色访问权限 |
| 在线展示 | Docsify（容器化） | 从 Git 生成自动构建站点 |
| 草稿/讨论 | Discourse | 共同推进想法的平台 |
| 内部图表 | Mermaid | Markdown 中嵌入的流程图，线框图等 |
| 外部图表 | Draw.io (.drawio → .svg) | 复杂架构图形 |
| PDF 导出 | Docsify + 统一 Vue.js 风格 | 用于离线阅读与客户交付 |
更多内容
在 схеме中还有待完善的工作点：
- Discourse 与 GitLab 的同步
- 审查和准备最终发布的流程的打磨
- 保持链接一致性
自动化发布、发现不一致并报告修正的机制。