在应该赏郁金香的季节来赏梅，自然是花已谢、人已散……
排版的故事
最近开始牵头部门发布一个技术期刊，看着初稿的排版有些惨不忍睹，于是自己用Python-Markdown + Pagedjs 写了一版简单的协作脚本。
不得不感叹，如果没有AI的帮助，可能无法在两个小时内完成完成Pagedjs部分的调整工作。
其实，后来发现，仔细阅读一遍官方的文档可能也就两个小时的事情，而最让我费尽心机的是如何让Pagedjs和MathJax配合使用的问题，在各种AI的提示下，并没有找到合适的答案。 最后还是通过搜索引擎找到了x.com 上的一个提示才得以解决。
我的文档习惯
和我接触比较多的同事，可能清楚我向来对文档的要求是比较高的：
- 基本要求文档必须做到结构化。能不用Word 就不用Word，尽量用Markdown 这类标记语言。
- 包括用到的流程图，也是尽量用PlantUML 生成的，而不是直接用Visio。
- 尽量要求做到版本控制，将内容放到Git仓库中。
- 如果可以，尽量软件架构设计类的文档最好和代码放在一个仓库，同步进行版本管理保持一致（其实大公司可能并不适用）。
二十年前的故事
对于文档格式的执着，可能源于我毕业后的一段工作经历。2004年，我毕业后在第一家公司做测试工作，公司有着比较完善的开发分工，当时产品的用户手册是由专门的资料开发工程师来撰写的。当然由于测试工程师对产品的了解更加深入，所以也会参与到用户手册的撰写工作。通常是资料开发工程师撰写初稿大纲，然后测试工程师在此基础上进行修改，直到完成。
当时整个文档的撰写工作是基于Word进行，但是作为一个刚毕业的新人，总是会弄乱Word的格式，经验丰富的资料开发工程师总是不厌其烦地在我搞乱的格式上帮我重新修改。久而久之，我觉得非常地愧疚，于是开始学习Word的排版规则，以便能够更好地协作。经常加班到很晚，就是为了把格式修改的更加接近标准。记得有次调整完所有格式，都到了凌晨2点，还需要保安帮忙打开公司的卷帘门才能骑着自行车出来。从此我便开始坚信文档是应该需要结构化维护的。
可是后来和资料开发工程师交流，才知道，当时更多走在前沿的公司已经开始使用RoboHelp以标签化的方式来撰写和管理文档了（这是一款1992年发布并至今仍在服役的软件）。不过我并没有机会正式地使用过这款商业软件。现在Jetbrains的 Writerside已经作为一款免费的插件在Jetbrains的IDE中提供。似乎也是一个非常不错的方案(一个轻量级的方案)。
所以作为程序员的我，自然是尝试在一些需要提供帮助系统的场景下使用模版生成html的帮助文档。再后来有接触了 DocBook、reStructuredText的方案，当然也尝试过Latex。
忘了何时起，Markdown开始流行，因为Markdown语法简单，而且Markdown基本做到了人机可读，所以，我开始尝试使用Markdown来写帮助文档。当然Markdown的标准不一致也时常带来很多困扰，所以也尝试使用Asciidoctor来做一些写作。不过在需要多人协作的项目上我还是倾向于回到Markdown，因为Markdown确实上手是最简单的。
我也会尝试用Markdown 来输出Word格式（Pandoc）。虽然可能这会让Word只能使用最基本的功能。但是我坚信结构化文档才是人机交互中最经济的格式，尤其在大语言模型流行的今天，Machine Readable 和 Human Readable 是需要并存的。
无论如何，我始终会感谢20年前加班的自己和那位向我分享资料开发经验的同事。结构化的文档习惯可能是我为数不多的好习惯。