做了模块给别人用。为了减少沟通成本，最好的方法就是写一个清晰明白的文档了。

    然而将文档写清晰明白了也不是一件容易的事情。我以前写文档时争取写清楚该模块的用途，各个接口如何使用的。

    今天，另一位调用我的模块的开发人员过来找我询问出现问题的原因。我焕然大悟，还是文档没写清楚。

    问题是这样的。这位开发人员会传入一个json格式的参数。这个json格式的参数是由我来定义的。我在我的文档中写明了json内部各个参数的含义，并且给出了示例，但是问题是：我没有给出各个参数的类型。当然，如果顺利的话，调用我模块的开发人员，从我的示例中应该会猜测出各个参数的类型。但是这样，也是花费了他们的思考成本。而我应该写得更明白些。

   举例来说，我给的示例如下：

{notification:{    ticker:test,    title:testtitle,    describe:describe,    icon:icon_name,    vibrate:true,    sound:true},}

    并且，文档中对各个字段有详细的说明，但是唯独没有说明类型。致使刚才那位开发人员在icon字段后填入的是0，而我这边是当字符串处理的。

    虽然它是json格式，只是所有参数中很小的一部分，但是如果我能注意到小处，对于json字段中的参数也说明类型，那么接口文档就更加清晰明白了。

    除此之外，不知大家还有什么更好的方法。