V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
aleen42
V2EX  ›  程序员

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

  •  
  •   aleen42 ·
    aleen42 · 2021-03-20 20:49:42 +08:00 via Android · 2825 次点击
    这是一个创建于 1104 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

    18 条回复    2021-03-25 23:26:46 +08:00
    codehz
        1
    codehz  
       2021-03-20 21:02:31 +08:00 via Android
    最纯的方法:用 HTML 写 HTML,用 PostScript 写 pdf
    aleen42
        2
    aleen42  
    OP
       2021-03-20 21:06:38 +08:00 via Android
    @codehz 有 Markdown 还用 HTML?
    JerryCha
        3
    JerryCha  
       2021-03-20 21:12:02 +08:00
    想了想,Lamy 可能还不够纯粹
    三菱 ub150 + 晨光 B5 活页本
    codehz
        4
    codehz  
       2021-03-20 21:14:54 +08:00 via Android
    @aleen42 抖个机灵而已,不用在意。想到一年前有个 hn 大火的文章说好多开发者写博客最后都变成写新的静态网站生成器去了(折腾主题也算吧)
    话说回来 Markdown 确实有很多局限性,虽然看起来过得去,但是真遇到点需求还得内嵌 html (然后大部分标签又会被 GFM 过滤),要说最纯粹,那肯定是省去这些中间步骤,一步到位直接写生成文件来的纯粹
    cassyfar
        5
    cassyfar  
       2021-03-20 21:19:30 +08:00
    Code is self-explainatory. Why do you need any documentation?
    aleen42
        6
    aleen42  
    OP
       2021-03-20 21:20:39 +08:00 via Android
    @codehz 😄,plain text writing 也能写出优雅的文档
    aleen42
        7
    aleen42  
    OP
       2021-03-20 21:24:17 +08:00 via Android
    @cassyfar 🤣 To tell others to read code directly.
    henryhu
        8
    henryhu  
       2021-03-20 22:25:14 +08:00
    我在改造 Hexo,让发布流程更加自动化
    hantsy
        9
    hantsy  
       2021-03-20 22:30:35 +08:00
    我十几年前开始用 Docbook, Docbook 组织文档真的专业。

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

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

    目前我熟悉的很多开源项目都是用 Asciidoc 。Spring 还有相关的开源项目,美化 HTML 页面。https://github.com/spring-io/spring-doc-resources/
    aleen42
        10
    aleen42  
    OP
       2021-03-20 23:06:51 +08:00 via Android
    @hantsy 👍
    aleen42
        11
    aleen42  
    OP
       2021-03-20 23:07:25 +08:00 via Android
    @henryhu 👍
    ClericPy
        12
    ClericPy  
       2021-03-20 23:56:04 +08:00
    技术文档... 还真问住了, 之前体验最好的貌似是 Dropbox 和自定义主题的 Github pages 或者 mkdocs (material), 其次是 readthedocs 不过后来不习惯了

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

    插眼看看其他人的推荐
    hantsy
        13
    hantsy  
       2021-03-21 10:38:04 +08:00
    @ClericPy 文档看哪些类型,Github Pages,MKDocs,Gitbook 更适应有组织性比较专业的文档(介绍一个项目,或者技术),可能只有程序员用得最多。

    Google Docs,Office 在线这种就比较大众化,几乎上就是代替本地 office 。
    ClericPy
        14
    ClericPy  
       2021-03-21 12:30:36 +08:00
    @hantsy 所以前东家的知识管理大部分都在 Google Docs 和 Dropbox 上, 协同编辑还是挺常见的, 最主要的是异步交流能节省太多时间成本了, 远超一切莫名其妙开会
    hantsy
        15
    hantsy  
       2021-03-21 13:34:56 +08:00
    @ClericPy 遇到不少公司用 Googole Apps 企业版本。
    ClericPy
        16
    ClericPy  
       2021-03-21 13:46:39 +08:00
    @hantsy 嗯, Google suites 可编程的地方还挺多, 早期没有 BI 时候还挺顶的. 其他家的实在没什么可用的, 微软家的早年间跨平台做的不行, zoho 帐号管理不如 Google 那边单点登录一切那么方便(配合了不少云产品的登录, 员工离职直接注销帐号), 至于国产的一堆 KPI 作品就不提了. 所以很多东西看似选择很多, 实际那个年头根本没的选.

    现在新公司里无知识管理的体验也挺神奇的, 员工离职不交接直接从头开始做, 隐性知识从代码里自己挖, 说多了都是累
    aleen42
        17
    aleen42  
    OP
       2021-03-25 23:06:07 +08:00 via Android
    @ClericPy 基本上很多公司都因為文檔的維護成本而放棄,特別產品文檔。這就導致很多複雜系統都只能靠翻代碼和歷史才能溯源。
    ClericPy
        18
    ClericPy  
       2021-03-25 23:26:46 +08:00
    @aleen42 加班都不是没理由的, 凑合过了
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3314 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 13:48 · PVG 21:48 · LAX 06:48 · JFK 09:48
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.