@xishuixixia
2015-09-28T04:25:46.000000Z
字数 3846
阅读 1790
开源
关于描述社区的建设、激励和教训的文档大家已经着墨了很多内容。到处的文章和博客都是围绕着社区管理的经营和启动作讨论的，如何让社区增长，如何支持社区，甚至有的是告诉你如何不要搞砸一个社区。
正如我在前面两篇文章内容为王和DevOps能为你的文档做些什么中所提到的，能够致力于追求质量上乘的文档，不仅仅对于用户有好处，对于贡献者也大有益处。如果好的文档能够帮到用户学习一个软件，那么它也一定能够帮助新的贡献者参与到项目中来，对不对？
哦，对了，当时间非常紧迫的时候有例外。如果项目的参与者很少的话，什么内容为王，什么DevOps，都帮不了你去写什么文档。当只有少数的开发者已经被到处都是不能正常工作点软件功所累而疲于奔命时，或者是为某些新的特性而兴奋不已，已经进入状态，撸起袖子准备大干一场时。但不知道什么原因，如何进入文档写作状态的教程却无从谈起。
当面临下面这些问题的时候，有多少开发者是作出类似回答的？
“我没有时间去为它写文档。”“它的文档是自动生成的。”“[\\喝多了，稍后修复。](http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered/185181#185181)”快进到几个星期或几个月之后。“这段代码没有文档！”“这段代码干了些什么事？”“我应该给它写点文档的......”
不是只有你一个人在战斗。文字仍然能起到它的作用。有时候它可能比写代码要麻烦些，因为它们也不会整洁的编译为二进制，但是它真的没有你想象中的那么的麻烦。
有很多种方法改进社区文档，而且在项目中大家各司其职，一定有相应的事情去做，而这根本无关乎他们的角色或是否有经验。无论你的项目是刚刚稍具雏形，还是已经运行多年，一定要花时间去改进写作和发布文档的协作方法，这意味着能够让你的贡献者们懂得如何并且轻松的融入到流程中。
记住，最为重要的事情，就是在协作、可扩展和保持简单上下功夫。现在我尝试描述下我曾经在开源社区看到过的，或者说亲身经历过的一些例子，即在开源社区中旨在增加开源项目好文档的参与度，以及在作者和工程师之间架设一座桥梁，从而填补他们之间的知识差异。
如果说代码贡献准则是帮助开发者入门和一些附加的标准，那么文档贡献的准则也是相同的目的。文档准则可以包括样式的约定，如何提交文档补丁的流程，以及那些代码贡献需要文档等等。
对于文档准则的唯一前提条件就是成功的贡献一些内容。下一次在你的项目中追踪文档的任务的时候，为什么不写一些注意事项或建议并且将它们分享给社区？在一开始就讨论以最佳的方式将文档整合进项目，这能够提醒参与者们这是一个值得讨论的议题。
需要一些例子从而带来一些灵感？可以参考诸如Django，OpenStack，KDE以及ArchLinux等项目的文档准则。
还有请记住，文档的提交通常比代码的提交风险要小的多。你必须尽可能的简化你的流程，且要保持你的说明清楚而简洁。如果你需要创建三个不同的账户，为了获取四个荣誉点而仅仅是修复了一个拼写错误，那么请你尽快的远离我，甚至都不需通过代码审核工具。
模版是可以将文档很好的标准化和模块化的，举个例子，看下README文件，每个开源项目都会以一个README文件作为入口，它放在显眼的位置，这对于让人们留下对文档的第一印象非常的重要。
其中的Python行者界，阅读文档的REDAME模版在很长一段时间成为了事实上的标准，Drupal项目也有基于章节描述的README模版，以及Fedora文档团队是基于文档“菜谱”的指导下工作的，它们不仅描述了如何贡献文档和撰写文档的准则，还用于模版本身。
没有时间制作模版？那就找一些例子来临时的替代！你可以选择一些你自己认为能够代表优秀的结构和格式的议题或内容的文件，将之囊括到你的新的文档中从而作为样例。任何想要作贡献的人，只要看到这些源文件，就至少能够对如何来组织标题和包含哪些章节有了一个基本的认识。
作为一名文档作者，这些都是我喜欢参与的活动，因为它们都涉及到直接参与到开源项目中，且能够立即得到和可重复性的结果。结合开发者深度的知识和软件的整体方法，对于技术作者来说，不仅能够获得对于文档深刻的洞见，对于整体项目的了解也非常的有益处。
我曾经很荣幸的参与过诸如fedora和NixOS的文档集中冲刺，以及组织KDE（过去）和Django（即将）的研讨聚会，这些集中冲刺和研讨聚会让我学习到了开源文档的内部运作的情况，举个例子，关于NixOS的情况，冲刺的结果不仅重构了3/4的文档，甚至还撰写了新的文档贡献步骤。
文档写作集中冲刺也是一种将新成员介绍给大家不错的方法，而且一般情况都会有更多的新人加入。在每次的Django girl的研讨聚会中，我都会在后续的进程中设立并参与为教程，组织手册，以及项目其它资源的文档写作集中冲刺。这是一个为新人介绍日常的Github工作流程很棒的方式，且同时还改进了文档。
近来，我很荣幸的成为第一个倡导在开发者的聚会中搞一个文档咨询台，这个聚会是著名的EuroPython 2015，我和Paul Roeland以及Maciej Szlosarczyk组成一个团队，我们穿上医生的帽子和长袍,开了临时的文档“诊所，为所有境况不佳的开源文档提供咨询和“诊断”服务。
在预计三小时，最后变为四小时的交流中，我们为来自15-20个项目的人们提供了咨询，就他们较为关心的问题，诸如如何重构文档结构，如何制作从原来的文档处理软件转为标记语言和源代码控制的计划，甚至是如何重构站点以让访问者更加容易的访问文档等等。
作为额外的收获，我们获得了进一步的整合和加强在开发者社区的文档讨论。在接下来的研讨会日子里，我们陆续听到那些错过的我们咨询的参与者，或者是不知道我们的参与者，称非常遗憾，因为他们曾经得到过我们的帮助。或许文档的咨询台和展位会是在开发者的会议中成为一种趋势？
技术作者要在开发者会议上分享关于文档的演讲。这绝对不是在开玩笑，我很欣慰的已经看到有很多人开始这么做了。在开发者大会中开发者分享关于文档的演讲也同样是被接受和鼓励的。当然，重要的是要作出能够吸引开发者们的眼球的主题。
在研讨会上关于文档的分享在第一次可能很难吸引那些开发者们，但是未尝不是一个收集信息和想法的好办法，至少，让开发者们对于文档有一个不同的认知。目前我最为喜欢的一个主题是FOSS DOC 101，因为它覆盖了更高层次的概念，目的是鼓励开源的开发者们认证的对待文档。
离TechComm会议已经有一段日子了，至今仍对会上的12个关于单一来源和没有单独的开发者可以掌控全局的讨论有深刻的印象。新一代的文档社区正在被关注，这要感谢开源的哲学，草根的合作以及各种大胆的实验。
我很自豪的参与到了文档的写作的分享。从两年前在俄勒冈的波特兰的一个一次小型会议开始，我就开始传播之旅，足迹遍布美国的各种聚会，包括两次大型的国际会议。它的使命：整合，而不是区别对待，通过创造给所有技术人员参与到关于内容的讨论中来的空间，来让文档在技术社区中占有一席之地。事实上，参加这些会议的有50%以上并非是作者，而他们代表的是各个开源技术和社区。
另外一个值得我们提及的是一个年度的会议：OpenHelp，它更加的聚焦于文档集中冲刺和开放的讨论。Open Help 邀请所有的开源项目聚在一起，搞得活动由：头脑风暴，黑客，基于本身内容的写作，通过预先选择的演示来传播讨论和激发人们。还有，你不一定非得是一名作者才能参加会议，会议的唯一条件就是你关心内容，关心开源！
我所谈论到的所有的这些想法，是离不开人们投入到实践中来的。这也是我个人能做到的极致了，所以我呼吁大家，无论是开发者还是作者，伸出你们的双手，共同开创一个协作的环境。
如果你是一名作者，不要犹豫，向开发者会议分享你的文档演示、集中冲刺或者工作室，你的专业的分享，开发者们就能够学习到你的经验，从我第一次参与到开源的世界，我在开发者会议，聚会以及文档冲刺等场合亲历了大家对于文档作者态度的改变，这要感谢这些公开的讨论，我们技术作者作为搭建知识的桥梁，填补工程与用户之间的缝隙，做我们应该去做的！
如果你是一名开发者，请向文档作者们伸出友好之手，邀请他们到你们到研讨会，聚会，和集中冲刺等，参加文档的研讨会，看看作者们是如何思考的，如何工作，以及在社区中是如何做的，每个人都能从质量上乘的内容中受益，而且作者对于分享自己所积累的知识的热情，一定能让你刮目相看，当然你也要助阵开源文档。你我同行，需要你做的就是伸出友好之手。
htcvwi8z.jpg?itok=f7t4N_Jf未知大小
Mikey Ariel， 著名开源项目oVirt社区负责人，目前是红帽的OpenStack平台的高级技术作者，工作地点在Brno，CZ，空闲时间，她是欧洲文档写作的领导者，Django girl的聚会组织者，开源项目的文档教练，在开源会议上是热情的演讲者，会谈及关于文档，敏捷和社区。请关注她的twitter：thatdocslady
查看英文原文：Docs or it didn't happen