解读API文档编写者的职位描述 | Medium

解读API文档编写者的职位描述

在技术写作领域，尤其是API文档编写者的职位描述中，往往存在许多问题。本文将通过分析职位描述中的常见问题，帮助求职者识别潜在的危险信号，并更好地理解API文档编写者的角色要求。

职位名称的重要性

职位名称是职位描述的第一部分，也是求职者对公司态度的第一印象。常见的职位名称如“技术作家”或“API技术作家”往往低估了该职位的专业性和价值。这并非对技术作家的贬低，而是反映了公司对API文档角色的重视程度。

一个更准确、更具专业性的职位名称，例如“API文档编写者”，能够更好地体现该职位的核心职责和公司对这一角色的重视。

职位描述中的问题

职位描述的内容往往能反映出公司对API文档编写者的理解程度。以下是一些常见的问题：

1. API文档被视为次要任务
   在许多职位描述中，API文档的编写通常被放在最后提及，甚至被视为附带任务。这种安排表明公司可能并未真正重视API文档的作用。

2. 职责模糊
   描述中常出现“创建各种文档”的要求，例如用户指南、技术参考指南等。这种泛化的职责分配可能意味着公司对API文档编写者的专业性缺乏认知。

3. 缺乏专业投资
   如果公司未能明确API文档编写者的专职角色，很可能意味着他们未在这一领域投入足够的资源和支持。

资格要求的陷阱

职位描述中的资格要求也能透露出公司对API文档编写的理解是否到位。以下是一些需要注意的信号：

1. 工具要求不当
   例如，要求熟悉“Madcap Flare”或“Microsoft Office”等工具，这些工具并非API文档编写的主流工具。相反，API文档编写更常用的工具包括Postman、静态站点生成器或代码编辑器（如Visual Studio Code）。

2. 术语使用不准确
   描述中提到“Swagger”时需特别注意。Swagger作为API文档工具的名称已逐渐被OpenAPI取代。如果公司仍在使用“Swagger”这一过时术语，可能表明他们对API文档领域的了解有限。

对中小企业（SME）的依赖

职位描述中如果提到需要依赖中小企业（主题专家）提供信息，这可能是一个危险信号。优秀的API文档编写者应具备独立工作的能力，能够通过阅读规范、使用Postman或实验来获取信息，而不是完全依赖开发人员。

与开发人员的沟通固然重要，但这应是信息补充，而非信息的主要来源。公司如果过于依赖开发人员，可能并未充分理解API文档编写者的专业性。

现有API文档的质量

在求职时，查看公司的现有API文档是一个重要的步骤。文档的质量往往能反映出公司对API文档编写的重视程度及其团队的专业水平。以下是一些常见的质量问题：

• 字段缺乏详细描述。
• 示例内容过于简单，如仅显示“string”或“null”。
• 语法错误频繁，句子不完整或标点符号缺失。
• 未标注必需的参数。

这些问题不仅会影响开发者的使用体验，也反映出公司在API文档上的投入不足。

面试中的应对策略

如果职位描述中存在多个危险信号，求职者可以在面试中主动引导对话。以下是一些建议：

1. 展示专业性
   在面试中，通过提出具体的改进建议，展示自己对API文档编写的深刻理解。

2. 强调独立性
   强调自己能够独立完成文档编写工作，而不是完全依赖开发人员提供信息。

3. 利用现有文档作为切入点
   如果公司现有文档存在明显问题，可以在面试中提出改进建议，展现自己的专业能力。

总结

一个优秀的API文档编写者职位描述应体现对专业性的尊重和对角色的深刻理解。如果职位描述中存在过多的危险信号，求职者需要在面试中主动展示自己的专业能力，并通过分析现有问题为公司提供价值。最终，选择一家真正重视API文档编写的公司，才能更好地发挥自己的专业优势。

原文链接: https://robertdelwood.medium.com/reading-api-documentation-writers-job-descriptions-92124e5d9008