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

用 markdown 文档完全替代 word 文档的可行性

  •  
  •   shijingshijing · 180 天前 · 6262 次点击
    这是一个创建于 180 天前的主题,其中的信息可能已经有所发展或是发生改变。

    目前公司正在讨论后续文档管理的策略,在方案选型的时候,在 word 和 markdown 之间有些犹豫。

    主要是分析了现有文档管理情况,然后考虑新项目的文档如何管理。大致情况如下:
    1.硬件团队的嵌入式的代码直接使用文本文件的 README,甚至用 ASCII 化简图(有非常 nb 的老工程师在驱动代码文件头部用 ASCII 拼除了芯片引脚和寄存器移位的示意图,这种只能膜拜,绝壁是不能动的)。
    2.软件团队内部主要使用 Sphinx,部分 java 代码相关的用 javadoc。
    3.系统架构、需求方面以 word 文档为主,有不少内嵌的 UML 截图,visio 截图。
    4.测试文档也是用的 word 编写,测试用例主要是 excel 模板管理,测试报告也是 excel 套 word 模板生成的,一边测一边填 excel,测完运行一个宏直接生成。
    5.用户手册也是用的 Word 模板,然后人工编写。
    6.各个部门内部有一些比较好的经验分享类的文章,也是用 word 编制的,很多都是图文并茂。

    现在的主要问题是这些文档都是独立的文档,公司想把这些文档做成某种能够在线检索的知识库,同时还要考虑以下问题:
    1,去微软化,彻底替换 word,而且不考虑 WPS,文档格式需要能够完全透明,根据自己的需要检索、解析或者批量处理,能用 git 进行版本管理。
    2,显示输出要保持同类型 word 文档的层次和条目,不能跟以前老项目的文档看起来有很大不同,细微的差别可以接受。
    3,必须能够像 word 那样在 A4 纸上分页打印输出,同时如果在线查看也能像 HTML 那样连续输出一整篇。
    4,能够导出成 pdf 作为离线的电子版发布。
    5,一篇文章作为一个文件,图片必须内嵌到文章里,不能以链接的方式单独存放。
    6,支持离线编辑,支持图文混和编辑,所见即所得。

    我已经在 word 上面做了大量尝试,包括使用 sharepoint 来进行版本管理,这套方案还是太厚重了,sharepoint 的版本管理和 git 还不太一样。另外在网上看见有方案是用 BASE64 编码图片然后内嵌到 markdown 文档里面,不知道较大的图片是否可行。文档格式方面其实没有特别复杂的需求,刚性的主要是图文混排,分段,加粗加黑,缩进这些,word 和 wps 的格式其实已经太复杂了,很多功能用不上。

    大家有没有其他好的实践,希望能分享一下。

    65 回复  |  直到 2019-07-25 10:31:01 +08:00
        1
    creanme   180 天前 via Android
    要不试试语雀?
        2
    gtlions   180 天前 via iPhone
    在一个 api 项目(几十个接口)中开始推广和使用 md,一直到现在,还行,技术类文档一般没啥问题
        3
    shijingshijing   180 天前
    @creanme 忘记说了,不能依赖任何外网的云服务。github 都不行。
        4
    dreamertn9527   180 天前 via Android
    base64 可行的,不过缺点是文件越大,越长。占用了不少编辑行。我有道云上的图片全是 base64 转的。
        5
    Nasei   180 天前 via Android
    一个图文混排原生 md 就不行了
        6
    ztcaoll222   180 天前
    markdown 对表格的支持并不完善, 比如分行, 合并, 除非写 html
        7
    tamlok   180 天前 via Android
    vnote and viki
        8
    shijingshijing   180 天前
    @dreamertn9527 我也比较好奇微软是怎么把 doc 文件里面图文混排做的这么厉害的。我看过有 BASE64 方案是把所有图片放在文章最后,然后正文中用 id 替换。

    还没尝试过 LaTex,感觉这个只会更麻烦。。。
        9
    lithiumii   180 天前
    3 和 4,导出和分页反正不难,markdown 用 pandoc 转 pdf 或者 docx 都挺完美的(完美的意思是足够支持我大学时候的论文排版需求)
    别的就不懂了
        10
    shijingshijing   180 天前
    @Nasei 所见即所得和图文混排主要是有很多非程序员需要使用,比如系统工程师编写系统分析文档,客户服务工程师编写用户手册,word 还是有优势的。
        11
    Nasei   180 天前
    @shijingshijing 是呢, 当然通过 html 怎么都能弄, 但拓展和标签加多了真的很麻烦, 第三方工具坑也多, 有段时间我甚至用 md 写 ppt 画流程图, 现在还是 office 走起
        12
    Vamposine   180 天前 via iPhone
    内部文档系统,是不是可以考虑内网搭个 confluence ……或者类似 gitbook 这样的
        13
    shijingshijing   180 天前
    @Vamposine 是的,这种类 wiki 的其实解决方案还是很多的,我们的难点在与离线编辑和图文混排,还要做到能够在线分享且能够版本管理。
        14
    uhian   180 天前   ♥ 1
    MarkDown 让我想起 dos 时代的 WPS,顺带想起了 CCED,中文之星……
        15
    jorneyr   180 天前
    不要折腾了,还是用 word 吧!
        16
    iyaozhen   180 天前 via Android
    @shijingshijing 内网 Wiki 速度差不多能当本地 word 用了
        17
    alinwu05   180 天前 via Android
    非技术人员用 md 很困难的,不要太理想化了
        18
    jdhao   180 天前 via Android   ♥ 3
    Markdown 复杂排版还是不行,楼上说的表格就是一个弱项,只能处理比较标准的表格,一旦涉及到单元格合并等等,就不行了。另外图片的并列等,也不太好弄,只能 hack。

    我最近在写一个文档,就是用 Markdown,然后使用 pandoc 转为 PDF,就需要用到 LaTeX 的一些知识,我自己懂,所以还好,你要做出精美的文档,不懂 LaTeX 是不太行的,但是让普通人学习 LaTeX,感觉难度比较高,不太好推广。

    我写了一篇从 Markdown 生成 PDF 的博文,把所有能想到的问题和坑都写了,地址在 https://jdhao.github.io/2019/05/30/markdown2pdf_pandoc/

    楼主可以试一下,遇到问题可以交流一哈
        19
    jdhao   180 天前 via Android
    @jdhao 另外关于图片的存储,既然你有 git,可以把图片和 Markdown 源文件放在一个 project,然后 Markdown 直接引用,生成 PDF
        20
    love   180 天前
    图片干嘛要和文本放在一起,没道理,操作修改和 diff 都不方便。
    表格复杂的直接在 md 里写 html 不就完事了。
        21
    dalieba   180 天前 via Android
    LibreOffice 来了解一下
        22
    dalieba   180 天前 via Android   ♥ 1
    这个可以依靠 Libo PlantUML 插件在文档里边直接用 UML 作图,须要外接 Graphviz 程序。
    https://bbs.libreofficechina.org/thread-2188-1-1.html
        23
    dalieba   180 天前 via Android
    Typora 通吃 Markdown/LaTeX,值得一用。
        24
    tennc   180 天前
        25
    tennc   180 天前
    Typora 通吃 Markdown/LaTeX,值得一用。 @dalieba +1
        26
    shijingshijing   180 天前
    @dalieba 没用过这个 Libo,我们的 UML 都是在 Enterprise Architect 里面弄的,功能强大。Typora 也在用,感觉离完全顶替 word 还差一截。。。
        27
    shijingshijing   180 天前
    @love 不可能叫做机械和模具的工程师用用 Beyond Compare 就已经不错了,vim diff 什么的太难为人家了,html 估计都得熟悉熟悉才行,负责客户培训的小 mm 也不可能写 html 的。图文混排和所见即所得是刚需。
        28
    kvker   180 天前 via iPhone
    本质上算是 html 替代 office ?
        29
    shijingshijing   180 天前
    @kvker 不一定是 HTML,但是应该算是 Markup language 替代不透明的 doc 文档。
        30
    zhuangzhuang1988   180 天前
    先比的上 reStructuredText 再说吧。
    拿个小砍刀去和导弹比。
        31
    secondwtq   180 天前 via iPad   ♥ 2
    ... Markdown “替代” Word 这种话也就只有程序员能说了

    这俩(或者说 Word,TeX 这俩和其他标记语言)根本就不是一个定位的东西,没法拿来比的。在功能性上,Word、TeX 和其他标记语言有十分巨大的 gap,并且这个 gap 中间是没有别的选择的,意思是你要么用 ASCIIDoc/reStructuredText,要么用 Word/TeX,要么妥协你自己的需求。( HTML 勉强能比,但是我觉得你都用 HTML 写东西了,干嘛不用 TeX ?)

    你把这些标记语言给拿给非程序员,人家没准会选 BBCode/Discuz! 代码,不为别的,起码人家功能强啊(就算如此好像还是没有解决最基本的图文混排)

    另外倒是有一些可视化编辑器很有意思,不过现在这年头的年轻人喜欢什么都往 Web 上面搬,这个歪风邪气本身就喝楼主要求离线的需求是相悖的 ... 所以¯\_(ツ)_/¯
        32
    secondwtq   180 天前 via iPad
    @secondwtq 据我所知目前在这个 gap 之间的只有这么几种选择:Markdown 的各种魔幻扩展,PHP,Madoko

    PHP 还有的救,Madoko 就是 TeX,Markdown 扩展跟 TeX 比就是这张图: https://gss0.baidu.com/-fo3dSag_xI4khGko9WTAnF6hhy/zhidao/pic/item/c9fcc3cec3fdfc033cfbce23d23f8794a5c226ad.jpg

    欢迎举出反例,因为我发现所谓 Markup language 的世界真的太单调了,我非常愿意了解还有几个能打的
        33
    haimall   180 天前 via Android
    看了半天 discuz 论坛最合适了😂😂😂
        34
    geelaw   180 天前 via iPhone
    呃 首先 docx 是标准化的,可以解压缩查看 XML。其次,自动化的检索等任务可以用 COM。
        35
    AX5N   180 天前
    标题的主语是谁?
        36
    widewing   180 天前 via Android
    要不。。eml ? 邮件客户端都能打开,支持可视化排版,图片编码为 ascii,完美标准化。。
        37
    fannas   180 天前 via Android
    看了一遍,latex 完全满足要求。
        38
    fannas   180 天前 via Android
    @fannas sharelatex 和 over leaf 了解一下啦
        39
    silentstorm   180 天前 via Android
    docx 已经全部是 xml 定义了,可以开发一个解析 docx 的程序。
        40
    luozic   180 天前 via iPhone
    你怕是不知道 word 早就做了规范化文档方案 ,内容都是存 xml 的。 业界好几种索引和检索 word 文档的搜索引擎,商业得好几个,免费还能私有部署的自己找找
        41
    wweir   180 天前 via Android
    解决了技术问题,再来考虑一下人?人、企业的接受能力,才是 office 这套软件最强的生命力
        42
    exip   180 天前
    用 libreoffice,除非你司都是程序员才有可能都用 markdown
        43
    FrankHB   180 天前
    不同文档面向的用户和维护需求不同,为什么要强求使用相同的实现?
    (要不需要编辑,直接 pdf 都行。)
    要强调检索那得结构化数据,都不应该保证存的是“文档”。
    去微软化?自己实现个 ISO/IEC 29500 ?
        44
    Stevenv   180 天前 via Android
    顶多只能技术部用 markdown
        45
    FrankHB   180 天前
    @secondwtq 能打的,是指不“单调”么? SGML 和 DSSSL 了解一下?(

    @exip 要表格什么的 md 就没救的……看这需求是没跑了。
    程序员也干不过 markdown 方言兼容和残废(比如 Bitbucket wiki )问题。
        46
    xuanbg   180 天前
    除了不能直接画图外,都没有问题。我们直接在 git 项目的 readme.md 里面写接口文档已经好几年了。
        47
    dalieba   180 天前 via Android
    @haimall #33 还有 phpbb、Discource
    @shijingshijing #26 那就来看看 http://url.slat.org/dwl-tw
        48
    mapper   180 天前
    word 是不可能被取代的,更大众化, 同样 markdown 对于技术人员来说也是无法取代的
        49
    FrankHB   180 天前
    @mapper 不,markdown 的竞争对手和备胎明显更多,个人使用现在能直接上车的就有不少。技术人员只会用 markdown 和某些服务只支持 markdown 会是个问题,但不会是长期的不可实现替代的问题。反过来,Word 不说实现,光是文档规格就别想随便整个替代,甭管你是不是技术人员。
        50
    mooncakejs   180 天前
    markdown 太简陋了。
        51
    liu19931020   179 天前
    Sphinx 用 reStructedText 挺好的
        52
    qqjt   179 天前
    别替代了,老老实实支持多种文件格式,txt、word、markdown 等等。
        53
    snw   179 天前 via Android
    Word 是非专业通用文本编辑器中最好用的,功能很全。

    但一旦你想做些专业的事情就会发现 Word 真是 bug 一大堆,样式、字体、表格、修订等等,经常莫名其妙就崩坏。
        54
    littlewing   179 天前
    confluence
        55
    l1ve   179 天前 via iPhone
    onlyoffice 不考虑一下?
        56
    lzhCoooder   179 天前
    LaTeX,全公司用一套大模板,每个部门在上面微调一下,以后每个人写起来就像在做填空题,并且格式完美一致,除了你说的所见即所得,其他需求都是最基本的功能
        57
    qianji201712   179 天前
    居然用 word 写技术文档 = =(求别碰),MarkDown 标配吧
        58
    jdhao   179 天前 via Android
    @lzhCoooder 表格就比较麻烦,另外 LaTeX 运行出错,debug 也比较麻烦
        59
    liu19931020   179 天前
    @lzhCoooder 你们的表格做的累不累
        60
    hzgit   179 天前
    confluence +1
        61
    Shingekinoshinji   179 天前
    用 latex 的话可以用 lyx 达到所见即所得的目的
        62
    shooter556   179 天前
    高级程序员每天最重要的工作是画 ppt
    md 能画 ppt ?
    ppt 不画出花来能唬住客户?
        63
    FrankHB   178 天前
    @shooter556 直接用 ppt 画 ppt 的基本是电脑中级高手。高级程序员里有不少各路奇葩玩意儿转 pdf 再转 ppt 的……
        64
    xmsz   178 天前
    如果只涉及开发,Markdown 足以
    如果涉及整个团队,肯定要线上第三方
    如果涉及整个团队,又不能线上,可以使用第三方部署内网
    如果涉及整个团队,不能线上也不能内网部署,那还是自己想用啥就用啥,别强求更浪费时间,大家还不乐意
        65
    PythonKGB   144 天前
    你们这完全是给自己增加工作障碍。
    我就纳闷了,技术文档怎么就不能用 word 写了呢?格式通用,任何人任何电脑都能打开,再复杂的图文混排,就没有解决不了的。
    反观 markdown,学习成本不说,你一堆 MD 文档,客户用户手册用这个?外部沟通用这个?还得给各个部门同事安装 md 应用去?
    别为了自己的想法,给别人找事儿。
    关于   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   4376 人在线   最高记录 5043   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.3 · 31ms · UTC 02:50 · PVG 10:50 · LAX 18:50 · JFK 21:50
    ♥ Do have faith in what you're doing.