文档！文档！

这个世界上会写字的应该要比会写代码的人多得多。但写点思路清晰的代码和写一份让人完全能读懂的文档都不是那么容易的事情。文档和代码这两件事情是相互影响的，鲜有见到文档写的好代码却写不好的事情，反过来如果一个项目文档写的很烂，那里面的代码肯定不会好到哪里去。

我现在由于所在行业的特殊性，需要和外面各种提供 API 服务的公司对接服务。这些提供 API 服务 90％ 的公司文档都写得有问题，没问题的那 10％ 是在行业做到顶尖的公司。

那些文档写得差的公司，不会意识好文档的价值。一份好得文档不仅仅是把问题定义清楚，它还会让项目的设计变得优良、规范。对于用户来说好的文档可以节约不少的时间，也能节约用户碰到问题时跑过来问你的时间。

下面以现在业界通用的 HTTP 协议为例，一份好的文档需要具备哪些基本的要素。

首先开发者自己必须要对 HTTP 协议烂熟于心，要完全按照标准返回 Head, Body, Response 这三要素。至于要不要完全用 Restful 标准，可以不用太在意，这不在本文的讨论范围内。

文档里面需要为每一个接口提供示例代码，世界上这么多语言你无法去为每种语言提供一份示例代码，那么就写个 curl 的调用示例好了（这就是为什么你必须要熟悉 HTTP 协议）。如果碰到那种不懂 HTTP 的开发者需要你提供一份他使用的语言的示例代码，你就让他去百度学习一下 HTTP 好了。

你的 API 里面少需要提供一个用来测试账号是否访问正常的就接口，因为这一块是在最容易出问题的。有了这样一个接口用户可以快速的排除掉这样的错误。

现在还有不少使用基于 HTTP 的 SOAP 做为向外界提供的接口。SOAP 这样的东西能丢掉就尽量丢掉，SOAP 是 Java 社区糟糕的产物。而且 XML 无论是对人对机器解析都很不友好，现在业界通行的做法是用 json。一旦定好一种数据格式就不要使用其他的格式（json 传文件可以使用 base64）。以免给用户带来额外的困惑。

我看到现在不少的 API 会有一些需要做 MD5 校验的操作，这样做是为了防止中间人攻击。这会给使用者带来额外的成本，这也是时代遗留产物，使用 HTTPS 根本就不会存在这个问题。

很多给企业提供的 API 方习惯了先商务洽谈，然后再提供相应的文档和账户。这里面存在的问题就是会有一个沟通传递的过程，这个过程中有可能会把文档忘记或丢失掉，并且文档一旦发给别人就无法修改了。既然使用了 HTTP，为何不把文档做为 HTML 直接输出到浏览器展现呢？一旦文档在线化了，更新就不是问题了。

文档里面的错别字就像吃饭时突然嚼到了沙子一样，会硌应一下。我的解决方法是不停的读，看到了错别字就马上修改，连续读三遍以上还没找到错别字就可以发布了。如果还有就继续改吧（在线化的好处！）。

对外提供的文档可以看出一个公司的很多问题，可以看出这家公司是否有做好一件事情的基本能力，可以看出他们自己对产品的重视程度。好的开发文档一个简单的标准就是就可以完全按照文档去做开发，并且不会有太多文档解释不了的问题。