创建好的API文档：工具和技术 [英] Creating Great API Documentation: Tools and Techniques

问题描述

我的任务是创建一个Web服务，由不同的开发人员使用不同的平台，为不同的公司工作，并且具有很大的技能水平。因此，我想为此Web服务API创建完整的文档，并且非常容易理解。虽然我确信这是一个崇高的目标，所有的文档项目都试图实现，但我还没有找到最好的工具和/或工作流程来帮助我的项目到达。

您是否发现自动生成文档工具足以为最终用户提供所有信息他们需要使用您的服务？

您是否找到基于Wiki的工具，轻松快捷地维护API的最新文档？

您是否找到了提供最好的两个世界的工具或技术 - 自动化和灵活性？是否存在简化API多个版本的过程的工具？

解决方案

我已经完成了博士学位。关于Java中的API文档。 Web服务显然是不同的，但我相信一些调查结果是全球性的。

首先，你必须接受这样一个事实：你将有两个类的读者。一个小班将是对每个功能进行完整阅读的人。与Java一样，您确实需要每个函数的API文档被完全指定。你不想让你的用户（或互联网论坛）猜到。不幸的是，这个类是相当小的，经常发生在关键任务客户端或有组织的代码审查。

API文档用户的更常见形式是我只是想做好事情的人物。他（或她）有一个想要完成的想法。他们也有一个想法在哪里找到它，所以让我们说他们已经找到你的功能。这里是问题开始的地方 - 他们真的不想阅读文档。现在假设你的电话有五个参数，四个显而易见，但有一个警告（例如仅发送一个公开的会话）。如果您通过参数列表并完全指定每个参数，他们会疲劳和滑动，而不会注意到关键的事情。我不能强调 - 人们完全不会注意到盯着他们的东西。这更棘手 - 如果他们相信他们完全了解功能，即使他们很难阅读文档，他们将会 - 跳过它。我看到人们在两句话文档的方法上缺少明显的注意事项。

所以这里是你可以做的：

1. 假设大多数用户实际上不会读取他们调用的函数的文档。事实上，你的API越直观，人们阅读文档的机会就越少。每个人都会读一个名字和20个参数的函数。但是，如果您写一个非常简单的API，并提出了一个令人讨厌的警告，那么您将冒着永远不会被阅读的风险。这里唯一的解决方案（我有一些Java，但不是为了网络）是为了避免惊喜。




2. 当您编写完整且完整的API时，明确突出显示不重要的位（我可以向您展示Java中令人惊讶的整个分类法，翻译）。更好的是，有三个人看文档，拿起不直观的东西。如果你不能把它们从API中加以考虑，那就突出显示出来。

Jeff Stylos也在API上做过博士论文）：为某些操作（即使是单独的网页）提供配方，并考虑在文档文本中为不属于API的方法创建占位符，但用户将会难以想象例如，如果许多用户想要做Z，但是在你的API中做的方法是做X，然后是Y，将文档添加到do Z占位符中，并告诉他们专门调用X和Y.

I'm tasked with creating a web service that will be used by several different developers using different platforms, working for different companies, and having greatly varying skill levels. As such, I would like to create documentation for this web service API that is both complete, and very easy to understand. Although I'm sure this is a noble goal that all documentation projects attempt to achieve, I have not found the best set of tools and/or workflows to help my project get there.

What tools and techniques do you find most useful in creating great API documentation?

Do you find auto-generating documentation tools sufficient to provide end users with all the information they need to use your services?

Do you find Wiki-based tools easy and fast enough to maintain up-to-date documentation of your API?

Have you found any tools or techniques that provide the "best of both worlds" - automation as well as flexibility? Do any tools exist that simplify the process of documentation multiple versions of an API?

解决方案

I've done my Ph.D. on API documentation in Java. Web services are obviously different, but I believe that some findings are global.

First, you have to accept the fact that you will have two "classes" of readers. One small class would be the people who do the complete read-through for every function. As with Java, you do want your API doc per each "function" to be perfectly specified. You don't want your users (or internet forums) to guess. Unfortunately, this class is fairly small, and often occurs with mission critical clients or with organized code reviews.

The more common form of API documentation user is the "I just want to get things done" type of person. He (or she) has a notion of what they want to accomplish. They also have an idea of where to find it, so let's say that they've found your function. Here is where the problem starts - they don't really want to read the documentation. Now suppose that your call has five parameters, four obvious but one has a caveat (e.g., "send only an open session"). If you go through the list of parameters and fully specify each, they'll get fatigued and skim and not notice the critical thing. I can't stress this enough - people will completely not notice something that stares them in the face. This gets even trickier - if they believe that they fully understand the function, even if they do bother to read the documentation, they will -most likely- skip it. I have seen people missing obvious caveats on methods with two-sentence documentation.

So here is what you can do:

1. Assume that most users will not actually read the documentation of the functions they call. In fact, the more intuitive your API is, the less chances are someone would read the documentation. Everyone would read a function with a strange name and 20 parameters. But if you write a really straightforward API with a nasty caveat, you run the risk of it never being read. the only solution here (I have some for Java, but not for the web) is to avoid surprises.

2. When you do write your full and complete API, explicitly highlight the nontrivial bits (I can show you a whole taxonomy of what is surprising in Java, a lot translates). Better yet, have three people look at the documentation and pick up the things that are not intuitive. If you can't factor them out of the API, highlight them.

Finally (and the credit here is to Jeff Stylos who also did his Ph.D. on APIs): Provide recipes for certain operations (even as a separate web page), and consider creating "placeholders" in the documentation text for methods that are not part of the API but users would concievably want. For example, if many users would want to do Z, but the way to do it in your API is to do X and then Y, add to the documentation a "do Z" placeholder, and tell them specifically to call X and Y.

这篇关于创建好的API文档：工具和技术的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！