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