最近帮老师整理一些文档, 老师原始文本是使用 word 进行编辑的, 考虑到参与的人可能并不只有我一个人, 于是就想着整成在线云文档, 方便多人针对选中文档进行发表意见及评论, 选用的是 飞书云文档, 基本能够胜任这个工作, 但是还有一些问题, 下文将讨论. 最终使用 markdown 进行版本管理.

文档能否像代码一样使用 git 进行版本追踪

飞书云文档 版本可以追踪, 乃至每一个变更都有对应副本, 这就意味着, 你可以随意回到变更历史中的任一版本, 有点类似 redis rdb, windows 系统镜像. 算是实现一个 完整回退 的一种方式。

但是目前 飞书云文档 并不支持变更说明, 也就是只有版本比对, 变更情况, 却不能为这些变更提供说明. 如我这次要把第一章内容进行校订, 然后更改了大量的内容, 然后进行了保存, 此时我想标注这个变更的意图目的及内容: 第一章内容整理及校订. 如果有了这个, 当变化历史很多的时候, 比如针对这本书做了一百次修订, 而每次修订都有相关的变更说明, 就可以很方便的进行目标版本回溯. 此时表更说明如同变更时间线中的一个个路标. 个人认为这个功能蛮重要的, 如果能够实现, 将会大大提高文档的管理能力, 尤其对于多次版本更改的文档相关工作. 目前未实现, 不知何故, 现见飞书文档数据保存应该是富文本, 绝不可能类似 word 那样自有文件格式及编码, word 不同于一般的文本文件, 有点像安装包二进制文件. 如果飞书文档数据是二进制, 要出变更内容, 需要对比, 此时对比问题将变得复杂. 如果是富文本倒是蛮容易实现的, 只需要考虑到默认样式的问题, 然后分别对各种文件格式进行解析, 解析成 飞书云文档 功能允许的格式即可.

不同于 word, epub, pdf 这种文件, markdown 显得更适合文本编辑, 尤其是对于只关注内容而言, 内容使用 markdown 格式管理极为合适, 常见代码仓库基本都是使用 markdown 来进行仓库说明, 如何使用等信息. 也有很多文章使用 markdown 进行创作只关注内容, 而不关注格式, 如本文即是 markdown 撰写.

目前考虑的是, 文档内容使用 markdown 进行相关管理, 文档格式使用 飞书云文档 进行管理, 文档之间的沟通及 消息交流 也使用 飞书. 这样有蛮多好处, 以下进行说明

  • 只关注文档内容的改动, 而不关注格式, 如标点符号, 错别字, 病句等, 这些使用 git 仓库及 markdown 能很好解决
  • 同样的文档可能因为面对读者的不同, 或者读者倾向不同而有目录的不同, 比如讲次目录, 内容目录. 这些目录的建立要基于内容, 但是内容是会变的, 所以最理想的方式是使用 git 版本管理, 建立不同分支, 不同分支对应不同目录, 同时又经常合并内容分支. 这样就很好解决了目录问题, 而这些功能基本上是借助 git 仓库管理
  • 如果有一天文档要发布到网络上提供浏览及传播, word 或者飞书文档都不能做到低成本转换为对应网页展示内容, 而与之相反的是 markdown, 现见有很多 markdown 静态框架, 比如 hexo hugo vuepress vitepress, 这些框架都支持将 markdown 转换为对应网页展示内容.
  • 如果有天比如出版社要发书排版, 只需要针对 markdown 内容添加目标样式即可, 也就是基本没有样式, 后面需要只需要添加样式即可

预期行为

这里展示一本文档从原始的 word 到多人协作各个过程

  • 我有一本文档, 原始为 word 格式, 我想进行该文档的修订工作, 修订每次变化及变化的原因都记录清楚, 每次变化都询问老师, 老师允许才进行变化, 每天把今天最初的最新版本同步给老师, 变化内容的指出可以很多人, 甚至网上的任何一个人

首先将 word 文档去除格式, 只保留最基本的格式, 比如空格换行之类的. 转换成 markdown 格式存储到 git 仓库中, 文件内容不进行改变和变更, 仅去格式. 然后将该 markdown 文件导入到 飞书云文档 , 这样的大家都可以针对该文档提出相关意见疑问, 或作文字符号, 病句校订. 这些校订内容以评论开始, 通过则进行内容更改, 不通过则说明理由, 结束为评论关闭. 这样大家可以只关注内容问题, 而不关注加粗不加粗等格式问题. 经过讨论, 与老师商议决定是否进行内容更改. 更改则作相关变更, 这些变更内容每天同步一次 markdown 仓库, 并提交相关变更说明. 这样就完成了每一个细粒度变更的追踪.

  • 我现在想生成两个目录, 一个是初始讲习目录, 一个是按照讲习内容制定的目录

首先 markdown 仓库主分支 master 是最新的文档内容, 如果单独指定目录, 可以基于 master 分支创建 A-dir 分支, 以及 B-dir 分支, 两个分支各干各的事情, 如果想要更新到最新的文档, 只需要合并 master 最新的内容即可.

  • 我现在想把所有的文章都发布到网站上

markdown 分目录简单处理, 选用一个喜欢的 ui 框架, 比如 hexo hugo vuepress vitepress, 将 markdown 文件 build 为对应网页, 部署到服务器上, 展示内容即可.

  • 现在群友想看到最新的修订版

只需要访问对应的飞书文档即可.

  • 现在老师想拿到经过他同意变更的最新版本

在线的 飞书云文档 直接导出 word 或 pdf 即可

  • 现在有读者想发表评论

只需要访问对应的飞书文档即可, 但是发表评论似乎需要注册飞书账号, 不像看时可以匿名看, 不知道飞书是否支持匿名评论.