ivan
1
# 标题：文档编写的难题与解决方案
## 1. 记录历史
我需要记录我的操作，补充文本图片和链接以及时间戳，避免主题在同一个草稿中交叉，并且能够轻松回忆起工作流程。
> 几次使用 Putty/Bash 记录日志帮助我在生产环境中恢复了混乱的操作序列。不要忽视这种可能性。
## 2. 发布
我希望将草稿转换为可用的文档并发布到项目文档中。最终结果是超越了最初的预期。
目标是创建具有扩展格式的草案，并像代码一样处理文档。
这使得节省了格式化和转换成标准发布的所需时间。
## 3. 在线格式
最终，Markdown+Git 允许自动生成在线文档。作为额外的优势，还有离线模式，可在浏览器缓存中访问。在客户的网络环境中以及飞机上，这种模式非常有用。客户也对此表示赞赏。
Markdown 用于 Gitlab、YouTrack 和某些消息传递应用程序，并且所有 LLM 模型都支持它。
## 4. 共享草稿
如果您的工作与财务无关，则您的草稿不应被隐藏。相反，允许其他人协作工作。
我的目标是使草稿公开可用，促成了“文档作为代码”的创建。DevOps 团队摆脱了无名的文本文件和搜索问题，“它在哪里记录下来了？”。这里没有 Word 不同版本的冲突、图像失真等问题。从草案中直接生成在线版本和漂亮的严格 PDF。
## 5. 今天的数据
- 使用 Markdown（Typora 或类似编辑器，具有自动保存 + 在 IDEA/PyCharm 中提交）编写
- 在 Gitlab 中存储（所有员工都可以通过角色模型访问，支持多人编辑）
- 自动生成为在线文档，使用 Docsify 容器（代码更新每分钟一次）；网站通过 DNS 投放到互联网上
- 可以轻松导出为具有与 Vue.js 网站相同的格式的 PDF
- 图表使用 Drawio (轮廓) 和 Mermaid (内联) 创建
- 将图表导出为 svg（偶尔导出 png 以供不兼容平台使用）并包含源文件
## 6. 不足之处
大多数用户对一个存储文档并且可以在多人模式下编辑的地方不感兴趣。贡献者很少，而普通用户很多。对于他们来说，快速找到最新版本的所需文档并轻松分享它很重要。因此，有几个问题需要解决：
1. 自动生成文档列表。
2. 根据文档的相关性对链接进行排序（而不是根据最近更新的频率，因为没有人关心仅仅因为一些小修改而将文档排在列表顶部）。
3. 允许直接在文档中进行小修改，而无需编辑源代码。
4. 批量更新文档，因为某些文档部分或完全重用。
5. 自动生成文档，因为它们会迅速过时。
6. 提醒需要对相关员工的公共渠道或社区中的回复进行调整或补充。这些回复的首要地位是权威性（与文档相关的个人的话比文档本身更重要，这是一个已知的现实）。