首页 > 代码库 > 怎样编写一份专业的技术文档
怎样编写一份专业的技术文档
对于开发人员来说,文档上很重要的。但是我看到很多的开发者,写出很好的类库,但是文档却不咋样,甚至是没有。和很多开发人员聊过,他们往往都会说没有时间去编写文档,或者说不知道怎么去写。其实我觉得还是重视的程度不够,你只有重视了才能写好。我们只要稍微留意一下就会发现,国外的软件都很重视文档,哪怕是开源免费的,也会把文档写得很好。
由于自己现在也在编写文档,所以把编写文档的一些要点提练出来,大家只要按着这个方法去写,写出来的文档肯定是可以的。先把自己在写的文档发出来给大家看看,欢迎板砖。
大家可以看看图中左边的文档结构图,这个文档里面包括了慨述、入门、API三大部份,这三大部份主要是帮助入户从了解,到入门,到熟练这么一个过程。
慨述
慨述这里包括了“简介”,“授权”,和“第三方类库”这三个要点,“简介”是让用户去了解你所开发的框架。在这里你要告诉用户使用了你的框架件有些什么好处。而“授权”告诉用户使用你的框架有些什么条件,能用在什么地方。我发现国内的很多作者都忽略了这点,这可能也和国内不注重版权这个大环境有关。“第三方类库”则告诉用户,你的框架里面涉及到哪些类库,因为这些类库也是有版权的。
入门
入门部份,是为了让用户能够在几分钟内上手你的软件,如果不能做到让用户在几分钟内上手,我想大部份的用户立马对你开发软件没有了兴趣。因为现在可供选择的太多了。所以在编写这份文档的时候,要以实例为主,实例的编写顺序由浅到深,对应的就是图中的“演练”了。
API
用户入门之后,还必须帮助用户熟练使用你的框架,这个时候你就需要具体介绍你框架里面的类库如何去使用这些 API,对于API的接口,一般都是以字母来排序的,这样做方便用户检索。
大家稍微留意一下,是不是觉得和 M$ 的文档编写有点类似呢?没错,这个文档结构基本上是参考了微软的 MSDN,向微软编写文档的开发人员致敬!
如果大家觉得我算是个不错的程序员,不妨关注一下我的微信。
怎样编写一份专业的技术文档