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

wms策略文档

我们是否可以首先同意文档很重要，而我们想要更好的文档呢？ 好。 这样一来，我就不必为为什么要关心而写三段式的报告了，这样您就可以保留更多的时间来阅读它会花费您的时间。

为了生意！ 作为在企业软件行业工作了近七年的技术作家，我已经看到软件用户，创建者和组织对技术文档的态度发生了巨大变化。 如果在我职业生涯的早期，我被教导要尽可能多地记录文件，那么如今，人们似乎更在乎内容质量而不是数量。

文档，中断

加入Red Hat之后不久，组织变革导致内容服务团队与面向客户的角色（例如技术支持，客户经理和客户体验经理）并肩作战，我们的变革无处不在。

这意味着我们需要认真应对并检查我们所做的事情 ，因为我们现在在我们产品的客户体验中扮演着至关重要的角色。 技术作家不再被我们的工程师所吸引，而是拥有正式的席位和发言权，并负有责任。

我们对如何处理文档进行了深入研究，得出的结论是，接近内容时最重要的问题是：

• 我们如何创建用户实际阅读的有用文档？
• 我们如何将内容创建无缝集成到我们现有的软件交付过程中？
• 我们如何才能使我们的社区以与贡献代码相同的热情来贡献于文档？

当然，没有人会生活在真空中，当我参与开放源代码社区并开始参加技术活动时，我遇到了表达这些问题或它们的某些变体的公司和项目，这显示了使我成为一个普遍趋势的趋势。非常高兴的文档女士。 激动人心的时刻！

在这个由三部分组成的文章系列中，我将尝试巧妙地使用开放源代码社区和Red Hat文档团队的成功文档解决方案的真实示例来回答这些问题。

在第一部分中，我将重点讨论第一个问题，该问题讨论了文档的原理。 然后，在以后的文章中，我将探讨解决文档演变的技术和社区方面的其余问题。

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

让我们看第一个问题：如何为正确的用户创建正确的内容，并在正确的位置和正确的时间将其交付给他们？

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

在这一点上，我想向Rich Bowen大喊大叫，Rich Bowen的文章RTFM在Opensource.com上的Doc Dish专栏上发表了文章？ 如何写一本值得一读的手册 。 他谈到了这种预见性的几个关键要素，我将在本文中对此进行扩展。

先问，以后写

内容策略的核心完全集中于内容的用户（读者）。 当我们记录特定的功能，组件或用例时，我们必须了解我们的读者。 在不尝试原创或重新发明轮子的过程中，我将使用著名的五个W来解释这一思考过程。

我的读者是谁？

正如Bowen指出的那样，创建有用内容的第一步是找出我要写的人。 我是在为最终用户，开发人员，业务分析师或系统管理员写作吗？ 我的用户是初学者还是忍者书呆子？

能够确定读者的角色（ GNOME帮助登录页面就是一个很好的例子）为您提供了基础，以构建对这些用户有用的内容。 现在，您可以在某些假设条件下询问其余问题，这些假设是关于读者已经知道的，他们的想法以及最有可能吸引他们的内容。

我的读者想知道什么？

这个问题不仅可以揭示读者想要的信息类型，还可以揭示我应该使用哪种格式来传递信息。 例如，当我面对在OpenShift Enterprise上为JBoss Fuse编写部署指南时 ，我必须真正专注于最小量的内容，这些内容将帮助新用户入门，而又不会向他们灌输他们所拥有的所有很棒的东西的信息。可以使用Fuse或OpenShift。

相反，如果要为开发人员创建命令行工具或库，则该工具提供的所有命令和选项的完整参考是产品用法的自然扩展。 是的，手册页可能是交付此类内容的最佳方法。 没有什么比奔跑的人[COMMAND]的乐趣大，并且可以找到很好的选项描述和示例。

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

这个问题是紧密联系在一起的后续哪里的问题，有时答案可以覆盖这两个问题，但是当独立解决，答案可以在软件使用或贡献我的读者很可能这一点透露给需要的是我的内容写作。

这意味着，如果您正在为Arch Linux之类的uber-ninja开源项目创建内容，则可以猜测读者已经尝试解决他们的问题或独立实现目标，因此当他们寻找文档时，不仅沮丧，而且已经知道他们在寻找什么。 在这种情况下，Wiki站点是无需强大的搜索功能就可以启用强大的搜索功能的完美方法，因为没有人有时间在这里浏览！

优点：在这一点上，您还可以开始考虑发布和整理内容的频率。 版本发布后，我的读者需要立即了解哪些信息？ 我们什么时候可以终止（早期版本）早期版本软件中的内容？ 等等...

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

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

可以使用Sphinx自动文档和JavaDoc之类的工具轻松地从代码中自动生成API引用，仅举几例。 投资于人类可读的代码注释不仅可以为您的用户提供帮助，也可以为需要从现在起六个月后更新代码的任何开发人员（包括编写它的开发人员， 让我们面对现实 ）提供帮助。

此外，错误消息。 他人不会发生任何事情，翔实而清晰的错误消息可以使用户免去对文档库的访问，因此没有理由不将其视为可在问题发生时立即向用户提供信息的正式内容类型。

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

这个问题可能是所有问题中最棘手的问题，因为它使您的内容的目的受到WIIFM （对我而言有什么意义）测试的审查：您为什么还要编写此内容？ 您为读者解决的是哪种痛苦？ 他们为什么会关心您在写什么？ 我知道，有很多难题需要回答。

如果我们回到读者在文章开头问过的问题—关于您是否同意文档很重要的问题—如果我（和我）不会花时间和精力写这篇文章。来自Opensource.com的聪明人）认为这对您没有用。

请记住，您正在阅读本文的目的是学习如何改进文档，如何社交化组织中的哲学变革，或者只是为了确保您并不孤单地以这种方式思考，我将试图以最有效的方式来构建这篇文章，并希望我能引起您的兴趣，使它到最后。

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

没错，我刚刚描述的方法可能与您的组织或社区如何查看和处理文档相距甚远。 我不会假定所有答案； 我能给的最好的建议是从小处着手，看看进展如何。

因此，如果您的公司雇用了几个技术写作团队，请与其中一个团队一起运行POC（概念验证）。 保持同事进度的最新进展，并记录所有发现和过程，供其他人选择采用此做法时使用。

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

自从我们在Red Hat开始这一旅程以来，我们在理解用户方面已经走了很长一段路，并且取得了可观的进步。 我们甚至有文档的内容策略师，扮演文档产品经理的勇敢者，并对内容进行重要的分析和分类，以便我们可以将精力集中在人们实际阅读的内容上。

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

剧透：涉及DevOps 。 （提示不祥音乐）

文件
碟

本文是Rikki Endsley协调的Doc Dish专栏的一部分。 要撰写本专栏文章，请提交您的故事创意或通过open@opensource.com与我们联系。

翻译自: https://opensource.com/business/15/6/documentation-content-strategy

wms策略文档