@xishuixixia
2015-09-21T06:26:07.000000Z
字数 3344
阅读 2505
开源
大家都认可文档的重要性吧？是不是都希望拥有更好的文档？本文不会再赘述文档为什么重要，因为我相信你最后一定会同意我的观点。文档确实很重要。
为了商务！作为一名在企业级软件界混了差不多快7年的技术作者，我看到过软件使用者、软件作者和软件组织对技术文档都有不同的看法。如果说我早期的职业生涯是尽可能多的去写文档，但是现在人们更加注重文档的质量而不是数量。
在我加入红帽的这段时间里，我们经历了非常大的改革，公司将内容服务团队变更为面向客户这边的定位，诸如技术支持、客户经理、客户体验经理等。
这意味着我们需要打起12分的精神来追赶和检查我们所做的一切，因为我们现在是产品的客户体验环节的重要角色。不再是躲在我们工程师背后的角色了，技术作者拥有了正式的地位和声音，同样也意味着更多的责任。
我们开始了一轮密集的调查，如何才能够写出更好的文档。我们得出了最重要的结论－硬性的－我们所提出的最为接近的问题：
当然，没有人可以做到与世隔绝，于是，我开始参与一些开源社区当中，也开始参加一些技术会议，我遇到了一些公司和项目也有这些问题或者说类似的问题，这说明了这是一个普遍存在的现象，这也证明了我作为docs lady的价值，多么的让人心满意足！
在此系列的三篇文章中，我试图去用自己切身经历的来回答上述这些问题，当然我自己的经历是可以说是非常成功的文档解决方案案例，这些均来自开源社区，以及红帽文档团队时的经历。
在此第一篇当中，我聚焦在回答第一个问题，讨论下文档的一些理念。然后，在剩下的两篇文章中，我讲继续回答关于交付技术文档以及社区方面的文档解决方案的问题。
让我们来看下第一个问题：我们如何才能够创造出正确的内容？给那些有真正需要的用户？然后在正确的时间和地点将之交付给他们？
如果你熟悉内容为王的概念的话，你可能非常想知道技术文档如何贯彻这一理论。内容为王不是针对那些诸如网站设计或版权所有的家伙们的吗？再也不要这么狭窄的理解了。如果你将文档视为单独的产品或者是作为软件的交付需求的话，我们必须规划、创建、交付和管理我们的内容，和其它可交付的内容同等的对待，而这意味这必须深入思考和规划。
在这点，我为大家推荐Rich Bowen，他发表在这里opensource.com的文章RTFM？How to write a manual worth readming? ，其开启了文档菜单栏目。他的文章涉及到关于文档的很多元素注入深入思考，我根据他的理论，扩展了几点。
内容为王的核心是完全聚焦在用户关心的内容上，即读者。当我们去为特性、组件或用例去写文档的时候，我们必须考虑到我们的读者。无所谓原创或者是重复制造轮子，下面我使用著名的5W来解释这一思考过程。
正如Bowen所指出的，创建用户的内容的第一步就是找到我为谁而写？我是写给最终用户的？还是开发者？还是业务人员？还是系统管理员？我的读者是初学入门者还是传说中的高手？
如果能够确定我的读者的角色（gnome帮助页面）为您提供了在其上构建，这将是有益的这些用户的内容奠定了基础。现在你可以基于确定的用户已知道一些什么，如何思考，怎么样的内容才能更加的吸引他们的假设的前提下，问一些其他问题了。
此问题所揭示的不仅是读者要什么类型的信息，还有我交付给用户的格式。举例来说，当我面临为OpenShift企业版写Jboss Fuse的部署文档时，我做的就是以最少的内容为新用户提供入门手册，而不是以庞杂而大量的信息或者是很cool的内容来轰炸他们。
相反的情况是，如果你为开发者提供命令行工具或某个库，一个所有命令的完整参考和工具提供者的所有属性则是产品使用的自然延伸。哦，或许一个man页是提供此类内容的最好办法；没有什么比运行man [COMMAND]更加的令人愉悦，且可以找到非常好的属性描述和实例。
此问题非常的接近接下来的“何地”的问题，而且有时候答案会覆盖它们两者，但是“何时”还是单独的拿出来表述了，答案可以表明软件的使用者或贡献者的突出点，我的读者需要我写什么样的内容。
这意味着如果你是为开源项目如Arch Linux的骨灰级玩家创建内容的话，你可以猜的到这些读者已经在尝试解决它们的问题了，又或者是独立的实现它们的目的。所以他们看到大篇的文档一定很烦，他们有明确的要搜索的内容。这样的话，维基百科是最好的实现途径，wiki强大的搜索功能使他们事半功倍，而不是浏览全部的内容，不是谁都有时间去浏览大量的内容的。
加分项：在此你可以思考多长时间release和清理你的内容。什么信息是在版本发布后读者需要立即就想知道的？什么时候结束早期版本的内容？等等......
还记得我在回答“什么”问题时提到的man页吗？这是一个非常典型而现实的例子，这种情况下一定是在终端下。同样的，当你交付一个IDE或桌面应用时，嵌入的或基于上下文的帮助会打破用户的体验。对托管在github上的项目有一个友好的README文件又是多么的重要。
API参考可以使用代码自动生成工具如Sphinx auto-doc或JavaDoc，只需命名即可。花时间在可读的代码注释不仅对用户有用，对于6个月之后的开发者们也非常多有用（包括开发者本人，请面对现实吧！少年）。
还有，错误信息。当发生问题时，清晰信息可以节省用户去查看文档库的时间。所有没有理由不为用户提供在发生问题时交付清晰的信息的内容。
此问题是所有问题中最为棘手而难以回答的。它将你的文档内容置于WIIFM（对我来说它内在是什么？）测试的审查之下：你为什么要写这些文档？你解决了读者的那些痛点？为什么他们要在乎你写了什么？我知道，太多刁钻的问题需要回答了。
让我们回到本文的开始，我问读者的一个问题－－首先你得同意文档非常的重要－－否则，我就不会花费时间和精力来写这篇文章。
记住，你阅读本文是因为你打算学习如何改进你的文档，如何在你的组织中进行理念的变革，即使是你对本文的看法持保留意见，我会试图构建本文中可能最有效的方式，并希望我鼓励你能够进行到底。
好理论，但是如果....
也许事实上是我上述所描述的方法论对于你的组织或社区掌控文档太过于遥远。我不可能知道所有问题的答案，我能给出的最好的建议就是从小做起，然后观察它如何发展。
所以如果你的公司拥有多个技术写作团队的话，写POC（概念验证）是其中之一，请保持你的同事能够紧跟流程，且记录你所有的发现，以及其他同事的流程，这就是我所建议的最佳实践。
如果你的开源项目缺乏技术写作能手，请到其他项目寻求帮助。协作是开源软件的支柱之一，没有理由不集中我们的资源，创造更好的文档，每个人都可以从中受益。
自从在红帽我们开启了文档点旅程，我们花了很长的时间去理解用户，方才取得了一点实质性的进展，我们对我们的文档有战略性的预期，对于文档扮演产品经理需要勇敢的灵魂，我们做非常关键的分析和归类内容，这样我们才可以在用户真正去读的文档上下足够的功夫。
当然，理念的变化仅仅只是一个开始，在下一篇文章中，我会试图解决成功的文档的技术层面的内容。
关于作者：Mikey Ariel， 目前是红帽的OpenStack平台的高级技术作者，工作地点在Brno，CZ，空闲时间，她是欧洲文档写作的领导者，Django girl的聚会组织者，开源项目的文档教练，在开源会议上是热情的演讲者，会谈及关于文档，敏捷和社区。请关注她的twitter：thatdocslady
本文由作者Nicole C. Engard发表在Opensource.com上：Content strategy: the new philosophy of technical documentation。经授权，在InfoQ中文站翻译共享。本文在Creative Commons BY-SA 4.0许可证下发布。