股票代码: 836286    股票简称: 易云股份
官方微信

扫一扫关注易云捷讯官方微信

备案 |       管理控制台

内容为王:技术文档新理念

原文:Content strategy: the new philosophyof technical documentation

作者:Mikey Ariel (关于作者详情会在文章后面介绍)

 

译者写在前面的话

就开放云精选目前的状况而言,所积累的内容多是文档,项目确实占的比重不大。那么一直以来,文档的读者问题,都是我思考的问题,我们提供了大约三种类型的文档:针对开发者的设计/实现思路、针对管理员的常见问题解决和故障排查、也有系统的针对入门者和学习者提供的手册/指南,此外,甚至还有少量为市场和咨询提供的案例描述。

但是,困扰我的问题依然存在,究竟谁是读者?会不会读?意义何在?

恰好今天看到此文,作者是红帽的 docs lady,而红帽在开源企业,除服务之外,文档绝对是一流的,很多开源的Linux/jboss入门和进阶者都从红帽的官方文档获益匪浅,也是其商业成功的秘密武器之一。

于是,通过翻译,学习下最优秀的文档工程师的感悟。也深入思考下自己的文档战略和方向。

 

以下是正文:

 

大家都同意文档是非常重要的吧?还有我们都希望有更好的文档吧?我们以此为前提,方才有下面的内容,否则的话,我可能要以三段论的方式给你解释为什么你需要明白,这样的话你还得花费额外的时间来阅读,最后还是得同意。很好,那我们开始。

为了业务!作为一名在企业级软件届混了差不多快7年的技术作者,我看到过软件使用者、软件作者和软件组织者之间对待技术文档的态度有很大的差距。如果说我早期的职业生涯是尽可能多的去写文档,但是现在人们更加注重文档的质量而不是数量。

文档的一点题外话

在我加入红帽后短暂的一段时间,我们经历了不折不扣的革命,公司将内容服务团队变更为面向客户的定位,诸如技术支持、客户经理、客户体验经理等。

这意味着我们需要打起12分的精神来追赶和检查我们所做的一切,因为我们现在是产品的客户体验环节的重要角色。不再是躲在我们工程师背后的角色了,技术作者拥有了正式的地位和声音,同样也意味着更多的责任。

我们开始了一轮密集的调查,如何才能够写出更好的文档。我们得出了最重要的结论-硬性的-我们所提出的最为接近的问题:

●  我们如何才能够创作出用户真正去读的有用的文档?

●  我们如何才能够将内容的创作无缝集成到我们已经存在的软件交付流程中?

●  我们如何才能激励社区成员像贡献代码那样有激情的贡献文档?

当然,没有人可以做到与世隔绝,于是,我开始参与一些开源社区当中,也开始参加一些技术会议,我遇到了一些公司和项目也有这些问题或者说类似的问题,这说明了这是一个普遍存在的现象,这也证明了我作为docs lady的价值,多么的让人心满意足!

在此系列的三篇文章中,我试图去用自己的切身经历来回答上述这些问题,当然我自己的经历可以说是非常成功的文档解决方案案例,这些均来自开源社区,以及红帽文档团队时的经历。

在此第一篇当中,我聚焦在回答第一个问题,讨论下文档的一些理念。然后,在剩下的两篇文章中,我将继续回答关于交付技术文档以及社区方面的文档解决方案的问题。

内容为王,技术文档新理念

让我们来看下第一个问题:我们如何才能够创造出正确的内容?给那些有真正需要的用户?然后在正确的时间和地点将之交付给他们?

如果你熟悉内容为王的概念的话,你可能非常想知道技术文档如何贯彻这一理论。内容为王不是针对那些诸如网站设计或版权所有的家伙们的吗?再也不要这么狭隘的理解了。如果你将文档视为单独的产品或者是作为软件的交付需求的话,我们必须规划、创建、交付和管理我们的内容,和其它可交付的内容同等的对待,而这意味着必须深入思考和规划。

在这点,我为大家推荐Rich Bowen,他发表在这里opensource.com的文章RTFM?How to write a manual worth readming? ,其开启了文档菜单栏目。他的文章涉及到关于文档的很多元素注入深入思考,我根据他的理论,扩展了几点。

先问,然后再写下来

内容为王的核心是完全聚焦在用户关心的内容上,即读者。当我们去为特性、组件或用例去写文档的时候,我们必须考虑到我们的读者。无所谓原创或者是重复制造轮子,下面我使用著名的5W来解释这一思考过程。

●  Who:谁是我的读者?

正如Bowen所指出的,创建用户的内容的第一步就是找到我为谁而写?我是写给最终用户的?还是开发者?还是业务人员?还是系统管理员?我的读者是初学入门者还是传说中的高手?

能够确定我的读者的角色为您提供了在其上构建内容的基础,这对用户来说是有用的。现在你可以基于确定的用户已知道一些什么,如何思考,怎么样的内容才能更加的吸引他们的假设的前提下,问一些其他问题了。

●  What:做些什么才是我的读者想要的?

此问题所揭示的不仅是读者要什么类型的信息,还有我交付给用户的格式。举例来说,当我面临为OpenShift企业版写Jboss Fuse的部署文档时,我做的就是以最少的内容为新用户提供入门手册,而不是以庞杂而大量的信息或者是很cool的内容来轰炸他们。

相反的情况是,如果你为开发者提供命令行工具或某个库,一个所有命令的完整参考和工具提供者的所有属性则是产品使用的自然延伸。哦,或许一个man页是提供此类内容的最好办法;没有什么比运行man [COMMAND]更加的令人愉悦,且可以找到非常好的属性描述和实例。

●  When:我的读者什么时候需要这些内容?

此问题非常的接近接下来的“何地”的问题,而且有时候答案会覆盖它们两者,但是“何时”还是单独的拿出来表述了,答案可以表明软件的使用者或贡献者的突出点,我的读者需要我写什么样的内容。

这意味着如果你是为开源项目如Arch Linux的骨灰级玩家创建内容的话,你可以猜的到这些读者已经在尝试解决它们的问题了,又或者是独立的实现它们的目的。所以他们看到大篇的文档一定很烦,他们有明确的要搜索的内容。这样的话,维基百科是最好的实现途径,wiki强大的搜索功能使他们事半功倍,而不是浏览全部的内容,不是谁都有时间去浏览大量的内容的。

加分项:在此你可以思考多久release和清理你的内容。什么信息是在版本发布后读者需要立即就想知道的?什么时候结束早期版本的内容?等等......

●  Where:我的读者在哪里消化这些内容?

还记得我在回答“什么”问题时提到的man页吗?这是一个非常典型而现实的例子,这种情况一定是在终端下。同样的,当你交付一个IDE或桌面应用时,嵌入的或基于上下文的帮助会打破用户的体验。对托管在github上的项目有一个友好的README文件又是多么的重要。

API参考可以使用代码自动生成工具如Sphinx auto-doc或JavaDoc,只需命名即可。花时间在可读的代码注释上不仅对用户有用,对于6个月之后的开发者们也非常有用(包括开发者本人,请面对现实吧!少年)。

还有,错误信息。当发生问题时,清晰信息可以节省用户去查看文档库的时间。所有没有理由不为用户提供在发生问题时交付清晰的信息的内容。

●  Why:我的读者为什么需要这些内容?

此问题是所有问题中最为棘手而难以回答的。它将你的文档内容置于WIIFM(对我来说它内在是什么?)测试的审查之下:你为什么要写这些文档?你解决了读者的那些痛点?为什么他们要在乎你写了什么?我知道,太多刁钻的问题需要回答了。

让我们回到本文的开始,我问读者的一个问题--首先你得同意文档非常的重要--否则,我就不会花费时间和精力来写这篇文章。

记住,你阅读本文是因为你打算学习如何改进你的文档,如何在你的组织中进行理念的变革,即使是你对本文的看法持保留意见,我会试图构建本文中可能最有效的方式,并希望我能够鼓励你进行到底。

好理论,但是如果....

也许事实上我上述所描述的方法论跟你的组织或社区文档处理太过于遥远。我不可能知道所有问题的答案,我能给出的最好的建议就是从小做起,然后观察它如何发展。

所以如果你的公司拥有多个技术写作团队的话,写POC(概念验证)是其中之一,请保持你的同事能够紧跟流程,且记录你所有的发现,以及其他同事的流程,这就是我所建议的最佳实践。

如果你的开源项目缺乏技术写作能手,请到其他项目寻求帮助。协作是开源软件的支柱之一,没有理由不集中我们的资源,创造更好的文档,每个人都可以从中受益。

自从在红帽我们开启了文档的旅程,我们花了很长的时间去理解用户,方才取得了一点实质性的进展,我们对我们的文档有战略性的预期,文档的产品经理需要勇敢的灵魂,我们做非常关键的分析和归类内容,这样我们才可以在用户真正去读的文档上下足够的功夫。

当然,理念的变化仅仅只是一个开始,在下一篇文章中,我会试图解决成功文档的技术层面的内容。

 

 

关于作者:Mikey Ariel,目前是红帽的OpenStack平台的高级技术作者,工作地点在Brno,CZ,空闲时间,她是欧洲文档写作的领导者,Django girl的聚会组织者,开源项目的文档教练,在开源会议上是热情的演讲者,会谈及关于文档,敏捷和社区。请关注她的twitter:thatdocslady

 

二维码.gif

关注易云微信号,浏览更多技术文档


© 2011-2017 易云捷讯科技(北京)股份有限公司, 版权所有 | © 2011-2017 Eayun,Inc. All rights reserved.

京公网安备 11010802022475号 | 京ICP备 11028869号

业务咨询:400-606-6396