本文介绍了 Mark Wentowski 关于 API 文档的各种组件、挑战和最佳实践的见解，强调了高质量文档对开发者体验的重要性，并提供了实用的建议和资源。

https://document360.com/blog/api-documentation-components-and-best-practices-with-mark-wentowski/

TechWriteX 的 API 文档专家 Mark Wentowski 谈论了 API 文档空间中的各种组件、挑战和最佳实践。

关于马克

马克的领英
在大学期间，马克没有太多选择。他发现了技术写作并喜欢它，因为它结合了写作和技术两个世界。最终，他获得了第一份初级作家的工作。
后来，马克发现了汤姆·约翰逊的博客“我宁愿写作”，这启发了他，让他觉得技术写作非常适合他。当他深入研究该领域时，他偶然发现了 Tom 的 API 文档课程，这使他将注意力转向 API 文档。

要点

在文档的正常阶段，您需要收集需求、用户研究、起草、审查和发布。而API 文档则提供了“开发人员体验”，这几乎就像用户体验一样。它还涉及用户研究中通常要做的所有不同事情，例如访谈、远程可用性测试、众包调查、问卷调查和评论。
“最常见的API文档类型是 swagger 文档，它是根据所谓的开放 API 规范自动生成的文档。开放API是API的整体结构，说明了API是如何编码的。”马克补充道。
在谈到 API 文档的不同方面时，Mark 表示：“其中一个方面是编写密集型文档，即概念性文档，从结构的意义上来说，它主要是用户指南。它首先是一份入门/入门文档，其中引导开发人员以最快的方式使用 API。”
“技术写作中最具挑战性的方面，尤其是在一个非常大的组织中，是面向客户的团队和文档团队的运营孤岛。您获得二手信息是因为他们从他们的角度提供这些信息。
此外，API 文档专家应该熟悉 Git、Markdown、静态站点生成器等。技术作家正在尝试尽可能接近开发人员，使用他们的工具和流程。有一个学习曲线，而且可能相当具有挑战性。”他继续说道。
在回答关于高质量文档是否会减少你的工作量的问题时，马克说：“它并没有真正减少你的工作量，而只是意味着你可以专注于写作之外的其他事情。例如，向您的网站添加功能或研究技术或花更多时间在策略上，您可能会将您的写作外包给其他利益相关者并成为审阅者。”
“拥有高质量的文档是一件好事，因为它可以让你扮演不同的角色并转换角色。”马克说。