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

[gancl]

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

[acgeo]

markdown

[hyzjshwo]

我们搭了个dokuwiki 文档扔上面

[zhkzyth]

产品的需求是word。

开发这边，后台我们用markdown把一些开发规范、设计方案之类的都用markdown。

[ggarlic]

楼主无非就是想需要个带版本管理的东东
无非就是
wiki、confluence、git+各种纯文本格式

我们用的confluence

[lujiajing1126]

api文档用swagger
或者wiki

[ryzn]

用html写文档。。。这么牛逼。

[gancl]

@acgeo @zhkzyth Markdown 表格支持不好,还要有学习成本,团队成员不一定会用

@ggarlic confluence还是收费的,我想找免费的或开源的
@lujiajing1126 感觉swagger不通用,想统一管理文档,而不只做api文档

[9hills]

@gancl dokuwiki，你值得拥有。。而且这货也不需要数据库，数据就是文本，直接定时打包备份就好了

[ivenvd]

还得用红色标注？Σ(っ °Д °;)っ

你们公司的 Word 不带审阅工具么？

[lujiajing1126]

@gancl 我们用dokuwiki。。比较轻量级

[miyuki]

tower.im 自带的文档功能

[mcfog]

我觉得先要想明白 — 你们写的文档的目标用户是谁？

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

没有工具能够兼顾所有需求，所以分不同场景选用合适的工具才最好

[jianghu52]

如果是给客户看的，那么我还能忍受，如果是给对内人看的，我觉得贴代码，结对编程都比维护文档要有意义多。
领导总是觉得，留下了文档，这个项目没了谁都能转。其实大家都知道，上年头的代码，哪个没几个地下室，真要是离开了某个熟悉的人，项目还就有可能停摆。

[cloudzhy]

wiki比较好，想写就写，不写就没有。

[gancl]

@mcfog @jianghu52 有对内,也有对外的.

[f3ngx]

texmacs这个软件很赞，wysiwyg（所见即所的），格式是文本（易于版本管理），快捷键还算方便、一些插入图表的特性不错、容易输出各种格式（pdf、ps、html...)，体积还算小巧（几十兆）

[loveuqian]

我们项目组用excel。。。。。。。。。。

[m1a0]

@ivenvd 正解

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

markdown什么的虽然可以通过版本控制来查看变更， 但是感觉是给开发人员用的， 对于非开发人员不友好。

[zerh925]

sphnix

[chinawrj]

@m1a0 用带UI的那种markdown感觉还好。当然没word强大啦