有更纯粹的办法来构建文档吗？

[aleen42]

不少大佬都会使用 GitBook, Vuepress, Jekyll 等工具来构建属于自己的技术文档，然后我在想最纯粹的方式不是直接沿用 GitHub Pages 吗？

所以我就写了个模板 markdown-only 沿用 GitHub Pages 内置的 GFM 及 Jekyll 来支持最纯粹的构建并直接套上 GitHub 沿用的样式来支持 dark mode 的显示。这样一来，维护＋构建＋发布都完全给傻瓜化了，各位大佬不就能更专注于自己写的干货和鸡汤（ bi ji ）吗？

[codehz]

最纯的方法：用 HTML 写 HTML，用 PostScript 写 pdf

[aleen42]

@codehz 有 Markdown 还用 HTML?

[JerryCha]

想了想，Lamy 可能还不够纯粹
三菱 ub150 + 晨光 B5 活页本

[codehz]

@aleen42 抖个机灵而已，不用在意。想到一年前有个 hn 大火的文章说好多开发者写博客最后都变成写新的静态网站生成器去了（折腾主题也算吧）
话说回来 Markdown 确实有很多局限性，虽然看起来过得去，但是真遇到点需求还得内嵌 html （然后大部分标签又会被 GFM 过滤），要说最纯粹，那肯定是省去这些中间步骤，一步到位直接写生成文件来的纯粹

[cassyfar]

Code is self-explainatory. Why do you need any documentation?

[aleen42]

@codehz 😄，plain text writing 也能写出优雅的文档

[aleen42]

@cassyfar 🤣 To tell others to read code directly.

[henryhu]

我在改造 Hexo，让发布流程更加自动化

[hantsy]

我十几年前开始用 Docbook, Docbook 组织文档真的专业。

现在 Markdown 居多，一般代码为主文档也简单。也在熟悉 Asciidoc，用得少。

如果觉得 Markdown 有局限性，应该试一下 Asciidoc，出版级别的支持。

目前我熟悉的很多开源项目都是用 Asciidoc 。Spring 还有相关的开源项目，美化 HTML 页面。https://github.com/spring-io/spring-doc-resources/

[aleen42]

@hantsy 👍

[aleen42]

@henryhu 👍

[ClericPy]

技术文档... 还真问住了, 之前体验最好的貌似是 Dropbox 和自定义主题的 Github pages 或者 mkdocs (material), 其次是 readthedocs 不过后来不习惯了

比较不爽的几次尝试比如 Google Docs 的代码格式化, 语雀累觉不爱...

插眼看看其他人的推荐

[hantsy]

@ClericPy 文档看哪些类型，Github Pages，MKDocs，Gitbook 更适应有组织性比较专业的文档（介绍一个项目，或者技术），可能只有程序员用得最多。

Google Docs，Office 在线这种就比较大众化，几乎上就是代替本地 office 。

[ClericPy]

@hantsy 所以前东家的知识管理大部分都在 Google Docs 和 Dropbox 上, 协同编辑还是挺常见的, 最主要的是异步交流能节省太多时间成本了, 远超一切莫名其妙开会

[hantsy]

@ClericPy 遇到不少公司用 Googole Apps 企业版本。

[ClericPy]

@hantsy 嗯, Google suites 可编程的地方还挺多, 早期没有 BI 时候还挺顶的. 其他家的实在没什么可用的, 微软家的早年间跨平台做的不行, zoho 帐号管理不如 Google 那边单点登录一切那么方便(配合了不少云产品的登录, 员工离职直接注销帐号), 至于国产的一堆 KPI 作品就不提了. 所以很多东西看似选择很多, 实际那个年头根本没的选.

现在新公司里无知识管理的体验也挺神奇的, 员工离职不交接直接从头开始做, 隐性知识从代码里自己挖, 说多了都是累

[aleen42]

@ClericPy 基本上很多公司都因為文檔的維護成本而放棄，特別產品文檔。這就導致很多複雜系統都只能靠翻代碼和歷史才能溯源。

[ClericPy]

@aleen42 加班都不是没理由的, 凑合过了