产品思维与丰富文档是实现开源项目价值最大化的利器

Posted on Sat 11 Oct 00:47 2014  Modify on Sat 11 Oct 00:47 2014

优秀开源项目的不断涌现对我们的技术水平提升起了很大的推进作用,作为开源社区的狂热爱好者,我也积极做出贡献,并努力完善自己的项目,希望获得积极的效果。

一直以来,开源广为受人诟病的是文档不够丰富的问题,使得开发者经常要从代码着手去了解,难度增大并耗时繁多,这限制了优秀项目的发展壮大。另一个问题就在于项目维护者并不十分注重使用者的体验,很少站在他们的立场去审视自己项目的缺失,也没有提供应有的便利使开发者们顺畅地使用自己的项目。

因此我在所做的项目中努力避免这些问题,并总结这个过程中的一些心路历程,尝试作出分析并介绍自己的解决方法。

要有做产品的思维

我们在开发中或多或少地对产品经理负责做好用户需求分析这种工作方式产生了依赖,以致轻视了培养自己的产品意识。我认为程序开发人员需要产品意识跟美术设计人员需要程序逻辑思维一样重要,特别是在做开源项目上,因为此时我们可没有产品经理可依赖。

做开源项目时我们应当适时跳出自己的本质,将身份转变为产品经理。产品经理的职责就是发掘并满足用户需求,此时其它开发者都可看作是你的用户,不太懂技术的用户。思考他们在查看你的项目时会想到的问题,尽量提供完善的指引,包括如果集成、如何测试、如何快速查看效果等等。

不要高估你的代码

做完一个项目后,你会感叹你做了出色的工作,并满足于你那些看似健壮的代码。但需要提醒的是,绝大部分时间里,只有你自己才认为你写的代码优秀,在别人眼中马上就变了样,哪怕是你现在觉得很好的代码,一年半载后再看回去估计你也没有了现在的优越感。所以永远不要想当然地以为别人应该从你的代码开始接触你的项目,有时候甚至将你的项目正确无误地导入到他们自己的开发环境中都成问题,更别说后续的事情了。

提供快速切入项目的便利

要让更多的人接纳你的项目并收获反馈信息,不能要求别人必须从代码入手。如果你做了一个java项目,你至少编译出若干jar给别人下载,最好能够发布到Maven上进行共享。如果你做了一个ruby的组件,最好的方法肯定是发布到RubyGems上。如果你的项目将输出显示效果,最好能提供运行截图或录制GIF动画来展示所得。如果你做了个iOS或Android应用,那就打包出安装文件让大家毫不费劲地看到你做了什么,而不是要人家导入你的项目再解决一堆错误后才发现你做的事情并不是他想要的。

如何写文档(注释)

产品思维的核心是:站在别人的立场去思考问题,写文档同样也需要产品思维。你要思考开发者会更关注你的那些功能点,对这些功能点的讲解要详细。你要思考开发者会对你的工作提出什么质疑,引导其消除这些质疑。你要告诉那些处于技术选型阶段的开发者,怎样将你的项目跟其它同类型项目对比。你要告诉开发者你在这个项目中用了哪些测试方案,证明你的代码经受了严谨的考验。你要尽可能多地列出项目所关注的领域中常见的问题或需求,讲述你的解决方案。

完善的文档通常包含多方面的内容:项目的起因、如何开始使用、核心原理、逻辑思路详解、可扩展性、优缺点、与其它同类型项目的对比、如何测试核心功能、预解答开发者可能感兴趣的问题等。

文档的写作过程需要回顾整体的逻辑思路,是巩固此次开发经验的最好方法,一份合格的文档比它背后的代码更能充分地证明你的技术水平。

面临怎样的心理压力

程序员普遍都不擅于表述,所以他们在做完项目后总会想方设法避免写文档,就算做也只是应付式去完成。在我的职业生涯很长一段时间里,我也同样存在这个问题,甚至直到几个月前我才意识到应该去改正。重新审视这半年间的经验,我总结出写文档的难点,其表现有两个方面:

  • 在写作过程中会迫使你回顾甚至质疑自己的想法,制造出焦虑感。
  • 希望语句简洁清晰地表达自己的逻辑思路但总不如愿。

用美好的收获来催眠自己

以上两个问题的表征可以总结为:写文档令我们很不舒服。对于刚从复杂的逻辑思绪中解脱出来,完成编码工作的我们来讲,重新回到困扰中这种折磨自己的事情毫无疑问会遭到本能的抗拒。但是,相信很多人都听过“成功者为自己找不适”的警句,只要我们坚持下来,就会发现其中的众多优点:

  • 写文档是换一个角度重新审视代码的过程。
  • 写文档是提高程序员表达能力的最佳途径。
  • 写文档能点燃我们重构代码的热情。
  • 写文档能培养自己更严密的问题分析能力。
  • 写文档能促使我们养成谨慎细致的开发习惯。
  • 写文档能帮助我们找出代码中某些不明显的错漏。

证明你的项目

文档基于代码逻辑,因此写文档的过程中我们肯定要根据逻辑去表达。我总能发现,在解释某逻辑的细节时会灵光一闪地察觉这个逻辑在满足某种我们未加以考虑的条件时可能会出错。于是我们会去证实自己的猜想,有时候这个求证过程会花费你一两天的时间,你需要从其它地方补充相关知识。最后改正错误的同时伴随着代码的重构,整个项目会因为每一次的改善日益健壮。也许你几天的改善只提炼出几句话的文档,但这些语句无疑更有说服力,更能体现你在开发过程中考虑问题的全面性,进而取信于人。

这也是一个温故而知新的过程,就像前辈分享技术,老师教育知识一样,促使讲解者在脑海中不断检验自己的所学,并尽量实现无错漏地阐释出来。每次的回顾都将使你的思维到达方方面面,从而养成严密的问题分析能力,对开始新工作时准确地预计难度及难点有很大的帮助。

展示你对待工作的严谨性

在工作中我一直要求自己做事要严谨细致,努力避免自己交出的成果收到诸如文字拼写不当、效果有偏差、细节问题繁多、明显逻辑错误的反馈。一个细致的程序员能在开发过程中考虑到产品经理无法想象的盲点,并提出专业意见,在验收阶段更能大大节省测试人员的时间。永远不要让同事由于你的一些哭笑不得的错漏而频繁与你思考人生,除非对方是妹子而你恰好对她有想法,同时对方不会因此对你的能力产生质疑。

事实上,我在工作中发现这种人从不缺少,我认为他们只是一心想把任务完成而忘记了提升自己水平,提升自己在别人心中的地位吧,总结一句就是:一个粗心的程序员不会得到同事们的认可。如果你很不幸也有这方面的缺点,那最好要有改变的意识,而写文档有助于我们解决这个问题,养成谨慎细致的好习惯。

表达能力限制了你的提升

对于服务于这个社会的任何人而言,提升表达能力都非常重要,只要数数书店里用于陈列此类型书籍的书架数量即可看出。而对于软件开发这个行业,我也一度以为只要程序代码写得好,表达能力可以排次序。当我彻底厌倦了中文技术社区毫无营养的灌水与争吵时,我转而投入了更有分享精神的英文社区。在领略了众多开发前辈们的卓越经验后,我意识到只查阅而不分享无法有效地提高自己的水平,充其量只是个人云亦云的搜索引擎重度依赖者。

这个转变令我进步很大,同时也发现了无论是英文还是中文,表达能力都发挥了根本性的作用,有时你可能用中文都无法表达准确,更别说英文了。需要澄清的是,这里所提到的表达能力不单纯指说出口的那种,更体现在经过一番思索后写出的文档。所以写文档是提高程序员表达能力的最佳途径,而你的表达能力决定了你未来的高度,锐意地培养自己这方面的本领非常有利于以后的发展。

方法论:选择最佳的文档载体

目前不少公司都采用老掉牙的Word作为载体来传播技术文档,最常见的是写接口说明书。Word最令人讨厌的是相当一部分的专业术语引发的拼写错误及由于版本或字体的原因显示不统一的问题。在Word中看代码更是一个灾难经历,不难想象那种缩进、自动换行导致的丑陋格式多么令人恶心。最重要的是Word无法进行版本迭代,很难取回之前的版本,标识新版本的更新点,这无疑增加了维护者的工作量,浪费查阅者的精力。交换文件的传播方式也提高了普及的成本,并不是明智的做法。

毫无疑问,文档最高端大气上档次的呈现载体只能是网页。浏览器每台电脑都有,Office就不是每台电脑都有了,就算有也可能被不同的厂商,不同的系统削弱文档的效果统一化。我曾经在团队内推广使用Github Pages的静态网页服务来展示开发文档,就像这个:ixiaoshuo。但似乎收效不大,可能是因为我的做法不到位,也可能是因为大家抗拒学习新知识。其实非常容易,使用简洁的markdown语法,配合Khaleesi来生成html,语法着色、版本管理都可以轻易实现,出来的效果绝对比Word精美一万倍。

方法论:应对一时语塞

我相信无论经验多寡,在写文档过程中对于遣词造句的纠结是每个人都会面临的问题。有时候真的一句话都想不出来,就像刚做完的项目对于自己来讲完全陌生一样。

列出文档提纲

我采用碎片化的写作方式来应对这个问题,在初期进行组织语言的时候,我想到什么要表达的就写什么,不强求将所有意思连成句段,也不追求用词准确,文字拼写,语句通顺等细节。因为纠结于语义只会让我们轻易地研进牛角尖,放大挫折的负能量。这种做法对于记下该表达的关键点有好处,道理跟列作文提纲一样,我曾经听过这样一个故事,说某杂志社见专栏作家迟迟不交稿,于是用让对方交提纲的方式催稿,结果第二天就收到了整篇文章。这个故事中杂志社让作家用总结文章中心思想的提纲来激发其思考,迂回地达成了自己的目标,只要提纲写出来,正文也就为时不远了。

慢工出细货

在总结出提纲后,我们实行逐个击破,思考该如何将每个环节的意思表达准确,用什么句式,用哪些词语等等。没有灵感时,可以尝试连接所有语句并通读几遍,会很容易地发现哪些地方该添加新内容。也可以搜索相关的技术文档,参考别人的表达及用词方式,发散自己的思维。不断重读此前写下的句子是一个非常行之有效的方法,就像重构自己的代码一样,今天可能想不出该添加什么去完善,那明天、后天、过几天再回来读读此前的句子,通常都会触动新的表述。不能强求毕其功于一役,要明白好的文档一定是经历过多次的删改,慢工才能出细货。如果太困难无法进行下去,那就彻底分神去干点舒服的事情,比如看看连续剧,上街去买买衣服,去海边吹吹风,就像放假休息一样,远离当前的烦扰,再返回时通常都能收获灵感与激情。

结语

写文档面临困难,但也实现收获,通过文档展示你的技术水平,展示你的工作态度,展示你的个性,展示你的思想境界,这些努力会照亮以后的职业道路。

作为例证,以下两个站点是我的经验总结来源:

希望能成为后来者迈出第一步的动力。