技术文档,其实也就是技术性的文档,比如公司技术架构的描述、各端的接口文档等,技术文档也是团队技术的一个沉淀,一般的团队都有文档,其文档的格式也可能不一样,但描述的大都是她,她,她...

ps:这里的"她"是技术的别名

这里简单介绍下我写技术文档的经历〜

第一版 - Word

来到北京,到美食天下的时候,正好负责改版,于是就要整理文档,比如项目开发的模式、前后端的约定、前端开发的规范、后端异步api接口、UX层的规范等,当时使用的是word,使用标题+文档结构模式来写了整个文档,当时也是美美的。并且我认为很成功,先不说技术模式用的前沿不前沿,起码使用的是一个很适合的模式,乃至于现在美天的所有底层还是使用的我当时写的。

由于后来接口的数量很多,导致文档略大,且不好定位,于是我不得不单独的把各个模块分为一个word文档。。。

ps:组件的使用文档是使用jsdoc生成的html版本,当然这得依赖你的注释〜

第二版 - Excel

后来我发现word里写的接口文档不太优美,通过@旭哥我知道了excel接口文档模式,大概的思路是:制作接口文档的模板,目录规范,然后我们就按固定的格式往里填充,界面的效果还是很棒的,比如目录是接口的分类(/1-用户相关/),文件名是接口的名称(用户登录.xlsx),然后我们要找哪个接口,就直接可以很准确的命中目录(分类)名,并进入文件夹里打开目标文档。也是美美的。

但后来发现使用excel也解决不了跟word一样的问题:合并冲突、查找内容的问题,于是...

第三版 - markdown

我跟@旭哥商量统一使用md文档来写接口+技术文档,目录的结构还是按/接口分类/接口名称.md来,使用md的好处是,因为是文本文件,冲突好合并,方便查找,但如果能有一个web版的预览功能就更帅了。于是我抱着试一试的态度,写了个递归抓取md生成目录树,并可实时预览。

gitbook

gitbook是一个可以把md文档生成html的工具,人家是写书用的,但其实完全可以做个web server来做文档预览用,比如:

使用git做版本控制,使用gitbook编译md->html,在内网搭建一个web server,当开发者git push时,web server负责拉取最新代码,并触发gitbook编译,其实小小的内网文档就实现了。

当然问题是,gitbook目前只支持md文件,由于生成的文档左侧有个导致,导致你要写个真的html做demo,编译后就有问题.

自己写个?

其实自己也可以写个,其实只做md->html文档比较好做,大概思路是:当访问/a.md时去获取该文件内容,并转成html,比如:

写完这个工具后其实最主要的就是如何把html文件与这个结合,因为html文件本身就是一个完整的文件,如何把她左侧放个导航呢?现在我是使用express截获.html的文件,然后页面插入一个iframe来加载这个.html文件,但感觉不是很帅.

update

经过我这几天的考虑,最终得出:node server只负责md->html,外层由nginx代理,已经写完并在团队内部先使用下. 也在百度搜索结果页组推开了git+md形式的文档风~

发表于 2015年11月02日 10:50:00 ,添加在分类 记事本 下 ,并被添加「 文档 接口文档 」标签 ,最后修改于 2017年04月23日 00:47:19