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

团队开发文档用什么来写最好? word, mkdown 还是 html?

  •  
  •   gancl · 2015-01-20 14:05:51 +08:00 · 8861 次点击
    这是一个创建于 3581 天前的主题,其中的信息可能已经有所发展或是发生改变。

    用word的话,如果哪个地方有更新,还得用红色标注,用git提交的log看还不知道改了哪些. 大家是用哪种方式写开发文档的?word,google doc, mkdown还是html?

    25 条回复    2019-10-30 18:51:17 +08:00
    acgeo
        1
    acgeo  
       2015-01-20 14:09:04 +08:00
    markdown
    hyzjshwo
        2
    hyzjshwo  
       2015-01-20 15:10:26 +08:00
    我们搭了个dokuwiki 文档扔上面
    zhkzyth
        3
    zhkzyth  
       2015-01-20 15:15:47 +08:00
    产品的需求是word。

    开发这边,后台我们用markdown把一些开发规范、设计方案之类的都用markdown。
    ggarlic
        4
    ggarlic  
       2015-01-20 15:15:57 +08:00
    楼主无非就是想需要个带版本管理的东东
    无非就是
    wiki、confluence、git+各种纯文本格式

    我们用的confluence
    lujiajing1126
        5
    lujiajing1126  
       2015-01-20 15:32:32 +08:00
    api文档用swagger
    或者wiki
    ryzn
        6
    ryzn  
       2015-01-20 15:56:25 +08:00
    用html写文档。。。这么牛逼。
    gancl
        7
    gancl  
    OP
       2015-01-20 16:17:56 +08:00
    @acgeo @zhkzyth Markdown 表格支持不好,还要有学习成本,团队成员不一定会用

    @ggarlic confluence还是收费的,我想找免费的或开源的
    @lujiajing1126 感觉swagger不通用,想统一管理文档,而不只做api文档
    9hills
        8
    9hills  
       2015-01-20 16:21:36 +08:00
    @gancl dokuwiki,你值得拥有。。而且这货也不需要数据库,数据就是文本,直接定时打包备份就好了
    ivenvd
        9
    ivenvd  
       2015-01-20 16:30:54 +08:00
    还得用红色标注?Σ(っ °Д °;)っ

    你们公司的 Word 不带审阅工具么?
    lujiajing1126
        10
    lujiajing1126  
       2015-01-20 16:32:39 +08:00
    @gancl 我们用dokuwiki。。比较轻量级
    miyuki
        11
    miyuki  
       2015-01-20 16:44:14 +08:00 via Android   ❤️ 1
    tower.im 自带的文档功能
    mcfog
        12
    mcfog  
       2015-01-20 16:48:17 +08:00
    我觉得先要想明白 — 你们写的文档的目标用户是谁?

    如果是对外的,给其他合作公司看的,那么pdf输出,changelog,乃至可调试的环境比较重要
    如果是对内的,自己备查或者指导新人的,那么日常维护方便,和代码结合紧密比较重要

    没有工具能够兼顾所有需求,所以分不同场景选用合适的工具才最好
    jianghu52
        13
    jianghu52  
       2015-01-20 16:56:52 +08:00
    如果是给客户看的,那么我还能忍受,如果是给对内人看的,我觉得贴代码,结对编程都比维护文档要有意义多。
    领导总是觉得,留下了文档,这个项目没了谁都能转。其实大家都知道,上年头的代码,哪个没几个地下室,真要是离开了某个熟悉的人,项目还就有可能停摆。
    cloudzhy
        14
    cloudzhy  
       2015-01-20 17:06:46 +08:00
    wiki比较好,想写就写,不写就没有。
    gancl
        15
    gancl  
    OP
       2015-01-20 18:10:58 +08:00
    @mcfog @jianghu52 有对内,也有对外的.
    f3ngx
        16
    f3ngx  
       2015-01-20 19:39:23 +08:00
    texmacs这个软件很赞,wysiwyg(所见即所的),格式是文本(易于版本管理),快捷键还算方便、一些插入图表的特性不错、容易输出各种格式(pdf、ps、html...),体积还算小巧(几十兆)
    loveuqian
        17
    loveuqian  
       2015-01-20 20:01:21 +08:00
    我们项目组用excel。。。。。。。。。。
    m1a0
        18
    m1a0  
       2015-01-21 11:28:30 +08:00
    @ivenvd 正解

    我们目前强制要求使用word的审阅功能, 有什么变更一目了然, 再配合版本控制工具, 查看两个版本之间的差别很轻松。

    markdown什么的虽然可以通过版本控制来查看变更, 但是感觉是给开发人员用的, 对于非开发人员不友好。
    zerh925
        19
    zerh925  
       2015-01-21 11:57:08 +08:00
    sphnix
    chinawrj
        20
    chinawrj  
       2015-01-21 12:44:08 +08:00
    @m1a0 用带UI的那种markdown感觉还好。当然没word强大啦
    guguai
        21
    guguai  
       2015-01-21 17:08:10 +08:00
    在看到这个题的时候,想一会就想到,一般在文档中需要图要进行形象的描述,虽然markdown可以加上图片链接,但是在你去看的时候,那时根本就看不到图片咧~
    jimrok
        22
    jimrok  
       2015-01-21 18:04:24 +08:00
    gitbook
    gDD
        23
    gDD  
       2015-01-22 17:06:37 +08:00
    @9hills 刚搭了一个用上,确实轻快,配上Markdown插件,能满足基本的文档编写归纳了!
    kshift
        24
    kshift  
       2015-02-08 16:00:58 +08:00
    Tower 的文档有版本功能,可以 diff 高亮显示区别。
    另外,Tower 的编辑器 Simditor 之后会增加文本高亮功能,也许可以满足你的需求。

    Tower -> https://tower.im
    balabalaguguji
        25
    balabalaguguji  
       2019-10-30 18:51:17 +08:00
    易文档很好用,应该是市面现在做的最好的,https://easydoc.top
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2624 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 24ms · UTC 03:39 · PVG 11:39 · LAX 19:39 · JFK 22:39
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.