今天，精彩继续，java培训班带我们一起来看看，要成为一名熟练的 API 文档作者，需要做哪些努力?

理解代码

理解代码包括理解代码本身、所用的平台、所用的技术、代码示例、用户的立场、测试代码等等。这个大类目前占主导地位，是 API 文档书写过程中最难的一个地方。

资料人员的工作通常会跨越多个产品或项目。因此，尽管开发人员可能只集中在一个领域(Java 工程师专注于 Java，C++ 工程师专注于 C++)，但是资料写作的人员需要分散在不同的领域，跨平台、产品、语言、技术等等。

与此同时，在学习掌握编程语言上，资料人员也有劣势。你花时间花精力去学习 Java，然而你有可能连着几周都接触不到任何代码。与此同时，当你只能间歇性并且很表层的接触到代码时，如何能深入的学习这一种语言呢?

从工程师那里获取信息

获取信息包括让工程师写注释、参与评审、提供信息、沟通变更的内容、帮忙检查代码、提供代码的访问等等。

通常一个接口在正式发布前，会经历数次评审，并进行高仿真的测试。而与此相反的，工程师在创建架构这个 API 时更孤立、更自主。当然，程序开发时有一个可用性指导方针，但是大部分资料人员距离参与到这其中还很远，甚至在 API 实现、编码、冻结、半测试之后才接触到这个设计。

结果就是，在最后的很短的时间段里，资料人员才参与进来，并被要求在所有端点的逻辑、参数、工作流程上加快速度。而这些内容毫无疑问在数个月前就已经进行了讨论、起草和设计(而当时资料人员并没有参与)。---很悲催有没有?

而且，开发人员通常深深的集中注意力沉浸在复杂的代码问题中，没有多少耐心来对待新手或者对编程语言不熟悉的人。如果你对这个编程语言的概念和原理不清楚，开发人员的解释对你来说也未必真正有用。开发人员通常认为他们的读者在该语言有相应的能力。

写作非参考文档

(概述、流程、介绍等)

非参考文档包括给出全景、解释概念、解释工作流程、简要描述接口调用和参考、介绍资料中的各个端点如何协同工作等等。

参考文档，包括端点或类，参数、响应值和其他的详细信息，往往都已经由工程师粗略的给出了。具有挑战性的事是理解端点或类之间如何相互搭配，如何利用 API 来完成真正的业务任务。这些指南(非参考文档)可能包含介绍、教程、基于业务任务的程序等等。同时会包括大量的需要开发人员来解释说明的代码样例，但是这份指南的交付却落在了资料人员的工作领域内。---这么有挑战性的事情，责任重大!!!

理解读者

理解读者包括理解开发者的需求和业务模式，从开发者那里获取反馈，目标读者应当同时覆盖专家和新手，了解程序员遵循的开发模式等等。了解企业的情况和业务规则，这样可以在资料中给出实际有用的建议与上下文。

像其他的技术资料写作情况类似，理解读者是向读者提供对他们有用的信息的关键。但事实上这个步骤非常具有挑战性：你要假设你的读者有什么样水平的知识?比如，你认为开发者是否知道如何用 Java 调用 REST?他是否知道如何处理 JSON 响应并在网页上特定区域显示?

一部分 API 文档的网站会提供多种语言的示例代码，但是更多的 API 会假设开发者知道如何使用自己的语言来调用。事实上，对于平台 API 来说的确可以假定：使用 Java API 的用户了解 Java，使用 C++ API 的用户了解 C++。但是对于 REST API，他们可以使用 Java、C++、JS、PHP 或者其他任何语言。最终输出的资料需要衡量读者的知识水平，这是一个巨大的挑战。如果你假设得太高，就会疏远新手用户;如果假设得太低，又会让有实力的开发者觉得烦。---知己啊，一针见血。

通过在资料这一块使用 GUI 的方法，这个问题也有变通：在可以折叠的模块中放更详细的解释，或者在代码样例中为经验丰富的开发者提供注释，而在后面给新手用户提供详细的解释。

识别依赖关系

这一类包括：检查输入、前提条件、合理性等。依赖关系一般会融入到指南或者全景的工作流程中去。例如，使用一个端点前需要满足什么前提条件?有的端点需要你从别的端点传递对象，也可能有其他先决条件或相关性。

总之，对于复杂的 API 来说，端点不一定是独立的个体。你可能需要首先创建一些东西到一定的状态，才能调用另一个端点并得到有意义的响应等等。

如何学习到需要知道的知识/技能?

---学习渠道很多

(开发者/自学/在线资源/自身有工程师背景/大学课程/书籍/资料)

好的工具事半功倍

Swagger

Swagger 是非常有竞争力的一款 API 文档写作软件，Swagger 提供一种简单的方式为 HTTP API 写文档,同时又方便 API 调用者测试。通 Swagger提供的相关 tools 可以很直观的在网页上浏览你的 API、测试 API、甚至通过解析 Swagger definitions(一个 YAML or JSON 格式的文档)，直接自动生成相关代码(swagger-codegen)。个人理解 Swagger 的核心就是 Swagger definitions，相关工具(Swagger Core、Swagger Editor)可以生成 Swagger definitions，(Swagger UI、Swagger Editor)解析 Swagger definitions 生成 UI 界面。

README.io

一款基于开发者的在线文档管理平台，为客户网站搭建开发者中心、开发者交流社区、文档管理、API 参考等功能。它的用户包括火狐、yammer、formstack 等。

README.io 的特色有：docs 文档众包保持文档的更新和正确性、API 浏览让用户尝试体验接口服务、每次更新升级的时间和内容、自定义 logo 和主题修改让用户完全实现自己的品牌化管理、工单客服支持系统来解答用户的问题等等。