内容策略：技术文档的新理念

我们是否可以首先同意文档很重要，并且我们希望文档更好？很好。这让我省去了写三段关于你为什么应该关心的长篇大论，你也省去了阅读它所需的时间。

进入正题！作为一名在企业软件行业工作了近七年的技术文档撰写人，我看到了软件用户、创建者和组织对技术文档态度的巨大转变。如果在我的职业生涯早期，我被教导要尽可能多地记录，那么现在看来人们更关心内容质量而不是数量。

文档，中断了

在我加入红帽后不久，当组织变革导致内容服务团队与面向客户的角色（如技术支持、客户经理和客户体验经理）并列时，我们经历了一场不小的革命。

这意味着我们需要认真地迎头赶上并检查我们所做的每件事，因为我们现在在产品的客户体验中扮演着关键角色。技术文档撰写人不再躲在我们的工程师背后，而是拥有了正式的席位和发言权，以及与之相伴的责任。

我们开始对我们处理文档的方式进行深入调查，我们得出的结论是，在处理内容时，最重要但也很难的问题是

• 我们如何创建用户实际会阅读的有用文档？
• 我们如何将内容创作无缝集成到我们现有的软件交付流程中？
• 我们如何吸引我们的社区以与他们为代码贡献相同的热情来为文档做出贡献？

当然，没有人生活在真空中，当我参与开源社区并开始参加技术活动时，我遇到了表达这些问题或其中一些变体的公司和项目，这表明一种普遍趋势让我这个文档女士非常高兴。令人兴奋的时代！

在这个由三部分组成的系列文章中，我将尝试通过巧妙地使用来自开源社区以及红帽文档团队的成功文档解决方案的真实案例来回答这些问题。

在第一部分中，我将重点关注第一个问题，即讨论文档的理念。然后，在后面的文章中，我将研究其余的问题，这些问题涉及文档发展的技术和社区方面。

内容策略：技术文档的新理念

让我们看一下第一个问题：我们如何为合适的用户创建合适的内容，并在合适的时间和合适的地点交付给他们？

如果您熟悉内容策略的概念，您可能会想知道这与技术文档有什么关系。内容策略不是网页设计和文案写作的东西吗？好吧，不再是了。如果我们将文档视为独立产品或软件的交付要求，我们必须像任何其他可交付成果一样计划、创建、交付和管理我们的内容，这意味着深思熟虑。

此时，我想向 Rich Bowen 致敬，他通过他的文章 RTFM? 如何编写值得阅读的手册 在 Opensource.com 上开始了 Doc Dish 专栏。他谈到了这种深思熟虑的几个关键要素，我将在本文中对此进行扩展。

先问问题，后写作

内容策略的核心完全关注内容的用户——读者。当我们着手记录某个功能、组件或用例时，我们必须了解我们的受众。我不想标新立异或重新发明轮子，我将使用著名的五个 W 来解释这个思考过程。

我的读者是谁？

正如 Bowen 指出的那样，创建有用内容的第一步是找出我为谁写作。我是为最终用户、开发人员、业务分析师还是系统管理员写作？我的用户是完全的初学者还是忍者级高手？

能够确定我的读者的角色（GNOME 帮助登陆页就是一个很好的例子）为您构建对这些用户有用的内容奠定了基础。现在，您可以根据对我的读者已经了解的内容、他们的思维方式以及哪些内容最有可能吸引他们的某些假设来提出其余的问题。

我的读者想知道什么？

这个问题不仅可以揭示读者想要的信息类型，还可以揭示我应该使用哪种格式进行交付。例如，当我面临为 JBoss Fuse on OpenShift Enterprise 编写部署指南时，我必须真正专注于最少的内容，这些内容可以帮助新用户入门，而不会用关于他们可以用 Fuse 或 OpenShift 做的所有炫酷功能的信息淹没他们。

相比之下，如果您正在为开发人员创建命令行工具或库，那么该工具提供的所有命令和选项的完整参考是产品用途的自然延伸。是的，手册页可能是交付此类内容的最佳方式；没有什么比运行 man [COMMAND] 并实际找到好的选项描述和示例更令人愉悦的了。

我的读者何时需要此内容？

这个问题与随后的在哪里问题密切相关，有时答案可以涵盖这两个问题，但当独立解决时，答案可以揭示我的读者可能在软件使用或贡献的哪个时间点需要我正在编写的内容。

这意味着，如果您正在为像 Arch Linux 这样的超级忍者开源项目创建内容，您可以猜测读者已经尝试独立解决他们的问题或实现他们的目标，因此当他们查找文档时，他们不仅感到沮丧，而且已经知道他们在搜索什么。在这种情况下，Wiki 站点是允许强大的搜索功能而无需在愉悦的浏览体验上投入太多精力的完美方式，因为没人有时间在这里浏览！

加分项：此时，您还可以开始考虑您发布和管理内容的频率。我的读者在版本发布后需要立即知道哪些信息？我们何时 EOL（生命周期结束）早期软件版本的内容？等等...

我的读者在哪里消费此内容？

还记得我在什么问题中提出的手册页吗？这是一个有效的内容放置的好例子，在这种情况下，它就在终端中。同样，当您交付 IDE 或桌面应用程序时，嵌入式或上下文相关的帮助可能会成就或破坏用户体验。对于您的 GitHub 托管的项目来说，良好的 README 首页的重要性几乎是不言而喻的。

API 参考可以很容易地从您的代码中自动生成，使用像 Sphinx auto-doc 和 JavaDoc 这样的工具，仅举几个例子。投资于人类可读的代码注释不仅可以帮助您的用户，还可以帮助任何需要在六个月后更新代码的开发人员（包括编写代码的开发人员，让我们面对现实）。

还有，错误消息。不是发生在别人身上的事情，信息丰富且清晰的错误消息可以节省用户访问文档库的时间，因此没有理由不将它们视为一种正式的内容类型，在问题发生时立即向用户传递信息。

我的读者为什么需要此内容？

这个问题可能是所有问题中最棘手的，因为它使用 WIIFM（对我有什么好处）测试来审查您的内容的用途：您为什么要编写此内容？您正在为读者解决哪些痛点？他们为什么要关心您写的内容？我知道，有很多难题要回答。

如果我们回到我在文章开头向您（读者）提出的问题——关于您是否同意文档很重要——如果我（以及来自 Opensource.com 的聪明人）不认为它对您有用，我就不会投入时间和精力来撰写本文。

考虑到您正在阅读本文的目的是学习如何改进您的文档，如何在您的组织中推广理念上的转变，甚至只是为了放心您并不孤单，我将尝试以最有效的方式构建这篇文章，并希望我能充分吸引您，让您读到最后。

伟大的理论！但是如果...

没错，我刚刚描述的方法可能与您的组织或社区看待和处理文档的方式大相径庭。我不会自以为是地拥有所有答案；我能给出的最好建议是从小处着手，看看效果如何。

因此，如果您的公司聘请了多个技术文档团队，请与其中一个团队运行 POC（概念验证）。让您的同事随时了解进度，并记录您所有的发现和过程，供其他人选择采用这种做法时使用。

如果您的开源项目缺乏技术文档专家，请向其他社区寻求帮助。协作是开源软件的支柱之一，没有理由不汇集我们的智力资源来创建每个人都可以从中受益的更好的文档。

自从我们在红帽开始这段旅程以来，我们在了解用户方面取得了长足的进步，并且取得了一些扎实的进展。我们甚至为我们的文档配备了内容策略师，这些勇敢的人充当文档的产品经理，并执行关键的内容分析和分类，以便我们可以将精力集中在人们实际会阅读的内容上。

当然，理念上的转变仅仅是开始。在下一篇文章中，我将尝试解决成功文档的技术方面。

剧透：它涉及 DevOps。（配上阴森的音乐）

本文是 Rikki Endsley 协调的 Doc Dish 专栏 的一部分。要为本专栏投稿，请提交您的故事想法 或通过 open@opensource.com 联系我们。