用户手册

用户手册

记得刚参加工作后，就接触到了电信大型机房里面设备的源代码，而这些代码是由一个个组件（component）组成的，就像积木一样，每个积木（组件）都有一份用户手册，这个手册面对的用户不是机房的管理员，而是搭积木的开发人员，因此手册的质量好坏直接影响了积木能否搭的好。组件都是用C语言编写的，而手册呢，大家可能见过微软的msdn的，在那个时候，需要一张光盘的容量，后来貌似是好几张，反正非常详细，我们的组件手册就是类似的东东，里面对于组件有个基本的架构介绍，使用场景分析，然后是提供的功能／特性介绍，接着就是这些功能／特性的API详细描述，最后是一些DEMO的示例代码。一份好的用户手册，能够帮助搭积木的人（二次开发者，架构师，测试工程师等）迅速理解积木（组件）的原理，快速搭建开发。而一份错误百出的手册，足以使机房的机器宕机N次，记得有几个月公司专门定期派人出差带在机房守着，半夜两点重启机器，为什么呢，因为不重启，很快就会宕机，而且很难恢复，所以问题没有被排除查出来之前，就像女人来了大姨妈一样，每个月总的出差一次。后来查找原因，根源在于用户手册API说明错误导致误用后内存泄漏。

这样的事情算是比较严重的了，因为一旦宕机，5分钟一个城市无法打电话发短信上网，那么电信运营商的损失少则几千万，多则上亿。其他因为用户手册的谬误或者读用户手册的人的理解错误导致的问题就更多了。曾经使用过Source Insight这个软件，也许你也用过，这个工具是一个阅读／分析代码的工具，当然也可以编辑，性能卓越，在没有atom／sublime text，github等之前，可以说这个工具是让开发者感觉异常幸福的工具，不但这个工具本身好，你是否看过它的用户手册，这个手册写的相当的好，既有面对小白用户的简要说明，又隐含了宏控制和可定制功能，手册语言深入浅出。

同样，atom工具是github开发的开源编辑器工具，工具好用用过便知，关键除了一般意义上的用户手册之外，专门出了Atom Flight Manual,易读性强，只不过大部分人可能读不完整,如果真的通读一遍了，那么对于编辑器，就会有和之前完全不同的思考角度，甚至它们录制了有意思的引导视频。

Atom Flight Manual开篇就是

Why Atom?

There are a lot of text editors out there; why should you spend your time learning about and using Atom?

Editors like Sublime and TextMate offer convenience but only limited extensibility. On the other end of the spectrum, Emacs and Vim offer extreme flexibility, but they aren't very approachable and can only be customized with special-purpose scripting languages.

We think we can do better.Our goal is a zero-compromise combination of hackability and usability: an editor that will be welcoming to an elementary school student on their first day learning to code, but also a tool they won't outgrow as they develop into seasoned hackers.

Atom和Source insight有个共同点，既适合于初学者使用，容易上手，又能够满足用起来后，逐步探索深度用法的群体。

当然关于Atom，我认为有一个点很有必要改进，就是它的插件，即packages，特别是每个package的使用手册，一个字，烂。

说到package，就会让人想起了nodejs，npm，看看这俩的API手册或者用户手册吧，相当不错，例子丰富，当然，也许这是许多人用起来的缘故吧。node的用户手册不用说了，有node的组织搞定。npm上面的package，用户量大的包自然也没有问题，话说大部分也是使用最常用的，所以相比之下，node的package部分用户手册还不错。

而关于用户手册，这个神器你不可错过。

DASH

Dash is an API Documentation Browser and Code Snippet Manager. Dash stores snippets of code and instantly searches offline documentation sets for 150+ APIs (for a full list, see below). You can even generate your own docsets or request docsets to be included.

除了各种语言／平台的用户手册外，他还有cheat sheets（不理解，到GitHub上面搜搜），cheat sheets还有ascii表（想当初可以打印出来贴在办公位前方的）和emoji等等（惊喜多多），甚至你还可以自己定义cheatsheet和用户手册，这对于提供各种SDK的网站／平台来说，多么好的工具啊。

不过有点可惜，只有mac平台和Ios平台有。

你看过的优秀用户手册是什么手册？（不限IT领域）理由？