去年七月，在 OKFestival 完整一周后，我设法找到足够的精力参加了 Write the Docs EU Berlin Unconference。我只参加了活动的一天，但这很值得，因为 Paul Adams，一位自由软件倡导者和 KDAB 的工程总监， 主持了一次讨论，我们在讨论中提出了帮助文档团队提高效率的规则
1. 选择一种标记样式并坚持使用
您选择的标记语言需要是您的团队认为最适合您所有需求的语言——尤其是一种可以轻松地从标记转换为输出格式的语言。创作工具并不重要。您可以让人们使用他们最喜欢的 文本编辑器 或编辑 wiki。这取决于团队的偏好。
2. 选择一个从输入到最终文档一致的工具链
关键是该工具需要自动且一致地生成输出。理想情况下，使用一个命令即可在所有输出格式中重新生成您的文档。
3. 始终以用户需要的格式生成最终文档
大多数项目都希望最终得到 HTML 网站或 PDF。
4. 为您的文档定义样式指南并强制执行
定义所有内容——语言细微差别、如何编写标题或在整个文档中使用的代词。
5. 始终考虑翻译
如果您现在不需要翻译，将来可能仍然需要。并非所有人都会说英语。最终您会想要进行翻译。我们有人希望将文档翻译成日语。在选择标记和工具链时，值得考虑翻译。（请参阅 翻译文档的 5 个技巧。）
6. 翻译基于一套主要的文档。
如果英语是您编写文档的语言，则让所有其他翻译都基于英语，这样可以轻松跟上文档的更改。
7. 特定于语言的样式指南
这适用于编程语言和人类语言。某些语言可能具有在编写官方文档时使用的特定代词。您的开发团队定义特定于编程语言的样式指南以保持一致性非常有用。
8. 为文档制定 QA 流程
如果您的文档中有教程，则它们需要进行测试，以便您知道何时代码更改破坏了教程。此外，对新文档进行文档审查。这对于安装说明和 API 文档尤其重要，因为这些文档很容易被破坏，并且会让您的最终用户感到沮丧。
9. 制定有关文档更新和存档的规则
如果您的文档过旧，请将其存档并从搜索引擎索引中删除。当文档<0xE2><0x80><0xAF>针对<0xE2><0x80><0xAF>旧版本中不存在的新功能时，请发出明确的通知。如果文档是您的<0xE2><0x80><0xAF>代码库的一部分，并且仅在新版本发布时更新，请制定一个流程来向后移植适用于较旧支持版本的文档。
10. 文档必须具有反馈机制。
最简单的方法是为文档设置一个错误跟踪器类别。
总之，最重要的是建立文档文化。文档不能是事后才考虑的事情——它需要成为发布过程的一部分。必须有一个流程，文档团队可以通过该流程了解需要文档的新功能。事实上，如果您能找到一位愿意支持文档事业的开发人员，那就更好了。虽然我会注意到，授权他们比用文档负担他们更有用，否则可能会导致倦怠。例如，不要将与文档相关的错误转嫁给他们。相反，赋予他们权力，让他们可以阻止因文档不足而推出的功能。
您还有其他建议吗？请在评论中告诉我们。
菜肴
本文是 Rikki Endsley 协调的 Doc Dish 专栏 的一部分。要为本专栏投稿，请提交您的故事创意或联系我们。
2 条评论