什么在外部Web服务的文档中很有用？

Question

我刚刚发布了一个web服务，并编写了一些相当原始的文档。我已经包含了输入参数和输出结果，每种Web服务方法的简短描述以及可能的错误示例。

我在文档中包含的内容几乎与我所使用的大多数Web服务的文档一致。我看了一下Twitter/Netflix /亚马逊的文档，并提出了一些我可以用来改进我的想法，但我认为Stackie社区可以提供一些意见。

• 什么样的“功能”使Web 服务文档使用 并有助于减少对支持时间 Web服务发布者必须花 处理的误解喜悦？

• 是否有 你有你错过任何你想要的东西的网络 服务文档中？

• 什么使web服务的 文件非常宝贵？

我知道它有很多问题，但我想用大刷子涂刷得到尽可能多的反馈，我可以。

Answer 1

例子是什么对我来说。我的理想文档有许多清晰标记的例子，用来说明有关技术的基本操作，并提示高级功能。他们不必绝对详尽。刚好足以让我知道如何在有用的情况下使用该东西。除此之外，关于它整体做什么（用输入，输出和方法解释）的清晰和详尽的描述是理想的。

一个很好的例子是the doc for SQLAlchemy。它被分成清晰的部分，描述了工具包的各个方面和优势。在这些部分本身中，该文档充斥着内嵌代码示例，可以引导您完成基本操作，并阐明如何进一步完善它们。我昨天刚刚开始使用SQLAlchemy，很快就能写出我以后的脚本。

Answer 2

我同意Evan Meagher。您可以做的最好的事情之一是提供使用您的Web服务的示例应用程序。你可以编写世界上最好的用户文档，但是人们会更喜欢能够看到自己的示例源代码。