我刚刚发布了一个Web服务，并编写了一些相当原始的文档。我已经包含了输入参数和输出结果，每个Web服务方法的简短描述以及可能的错误示例。
我在文档中包含的内容几乎就是我所使用的大多数Web服务的文档中的内容。我已经看了一下Twitter / Netflix /亚马逊的文档，并且有一些我可以用来改进我的想法，但我认为Stackie社区可以提供一些意见。
什么样的“功能”使网络 服务文档使用愉快 并帮助减少支持时间 Web服务发布者必须花费 处理误解？
您是否在网上遗漏了任何内容 您希望的服务文档 你有吗？
什么可以创建一个Web服务 文件无价值？
我知道很多问题，但我正试着用大笔画来尽可能多地获得反馈。
答案 0 :(得分：3)
例子是对我有什么用。我理想的文档中有许多清晰标记的示例，用于说明相关技术的基本操作并提示高级功能。它们不一定非常详尽。足以让我了解在有用的情况下如何使用该东西。除此之外，对其整体性能（包括输入，输出和方法解释）的清晰而详尽的描述是理想的。
一个很好的例子是the doc for SQLAlchemy。它分为明确的部分，描述了工具包的方面和优势。在这些部分中，文档中充斥着内嵌的代码示例，它们将引导您完成基本操作，并阐明如何进一步学习它们。我昨天刚开始使用SQLAlchemy，并且能够立即编写我以前编写的脚本。
答案 1 :(得分：1)
我同意Evan Meagher的观点。您可以做的最好的事情之一是提供使用您的Web服务的示例应用程序。您可以编写世界上最好的用户文档，但是人们会更希望能够自己查看示例源代码。