关于社区建设、参与和留存的文章已经有很多了。围绕社区管理的讨论如火如荼，到处都是关于如何发展、支持和不搞砸开源社区的文章和博客帖子。
正如我在之前关于内容策略和文档的 DevOps 的文章中提到的那样，高质量的内容正悄然走到前台，它不仅对用户有价值，对贡献者也很有价值。如果好的文档可以帮助新用户学习您的软件，那么它也可以帮助新的贡献者参与到您的项目中，对吗？
没错。 除非当关键时刻来临时，如果社区不参与，所有的内容策略和 DevOps 都无法帮助您的项目文档。 当一些开发人员厌倦了某些东西无法正常工作，或者对创造新事物感到兴奋时，他们会攻占城堡并使其发生。 但是不知何故，如何攻占城堡的教程却无处可寻。
要记录还是不记录？
当面对这个问题时，有多少开发人员说过这些（或类似的）话？
“我没有时间记录这个。”
“它是自文档化的。”
快进几周或几个月后...
“这段代码没有文档！”
“这段代码甚至做什么用的？”
“我应该记录这个的...”
你并不孤单。文字是工作。有时它们比代码更难，因为它们不能整齐地编译成二进制文件。但它们并没有你想象的那么难。
帮助您的社区自助
有很多方法可以改进社区文档，并且项目中的每个人都可以做一些事情，无论他们的角色或经验水平如何。 无论您的项目刚刚成型还是已经运行多年，花时间改进贡献者编写和发布文档的方式，都意味着您的贡献者可以更独立、更轻松地遵循此过程。
要记住的主要事情是，这些努力需要是协作的、可扩展的和简单的。 我现在将尝试描述一些我从开源社区中看到或参与过的活动示例，这些活动旨在提高开源项目对更好文档的参与度，并弥合编写者和工程师之间的知识差距。
文档指南
如果代码贡献指南旨在帮助开发人员入门并遵守标准，那么文档贡献指南也具有相同的目的。 文档指南可以包括样式约定、如何提交文档补丁的程序以及哪些代码贡献需要文档。
贡献文档指南的唯一先决条件是成功贡献一些东西。 下次您在项目中处理文档任务时，为什么不写一些笔记或建议并与社区分享呢？ 仅仅开始讨论将文档集成到您的项目中的最佳方式，就会提醒人们这是一个值得讨论的话题。
需要灵感？ 查看像 Django、OpenStack、KDE 和 ArchLinux 这样的项目，了解一些文档指南的示例。
请记住，文档提交通常比代码提交风险更低。 您应该尽可能简化流程，并记住保持说明清晰简洁； 如果我需要创建三个不同的用户帐户并获得四个不同的业力积分才能修复一个错别字，您会比您说“Gerrit”的速度更快地让我失去兴趣。
模板
模板非常适合标准化或模块化文档。 以 README 文件为例。 每个开源项目都以 README 文件开头，这使其成为一个非常显眼且重要的第一印象文档。
在 Pythonistas 中，Read the Docs README 模板 一段时间以来一直是首选标准。 Drupal 项目也有一个带有章节描述的 README 模板，Fedora 文档团队一直在开发一个文档食谱，其中包含主题“食谱”，不仅描述了如何贡献文档和编写指南，还可以用作模板本身。
没有时间制作模板？ 例子怎么样！ 您可以选择一个您认为代表良好结构和格式的主题或内容文件，并将其包含在您闪亮的新文档指南中作为示例。 任何希望贡献的人都可以查看源文件，并至少了解如何构建主题以及应包含哪些章节的基本概念。
文档冲刺、黑客节和研讨会
作为一名作家，这些可能是我最喜欢的活动，因为它们涉及与开源项目的直接互动，并且通常会产生立竿见影且可重复的结果。 将开发人员的深入知识和技术作家对软件的整体方法相结合，可以真正深入了解不仅是文档，还有项目的整体可用性。
我有幸与像 Fedora 和 NixOS 这样的项目一起冲刺，并为 KDE（过去）和 Django（未来）举办了文档研讨会。 这些冲刺和研讨会帮助我了解了开源文档的内部运作，例如，在 NixOS 的案例中，导致对四个主要手册中的三个手册的源文件进行了完整的重组，以及新的 内容贡献程序。
文档冲刺也是向您的项目介绍新贡献者以及向开源领域介绍新人的好方法。 在我参与的每一个 Django Girls 研讨会中，我都确保包括一个后续的 文档冲刺，用于教程、组织者手册和该计划的任何其他资源。 这是向新人介绍真实的 GitHub 贡献工作流程，同时改进文档的好方法！
帮助台和展位
最近，我很荣幸在一个开发者大会上领导了有史以来第一个（我想？如果我错了，请有人纠正我）文档帮助台，该会议是 EuroPython 2015。 我与 Paul Roeland 和 Maciej Szlosarczyk 合作，我们戴上我们的文档（医生）帽子和长袍，并为您的所有开源文档需求开设了一个弹出式文档诊所。
在我们三个小时变成四个小时的会议期间，我们咨询了来自大约 15-20 个项目的人员，他们有非常有趣的问题和疑问，例如如何重组他们的文档集、创建从传统文字处理软件到标记语言和源代码控制的迁移计划，甚至重组项目网站以使文档更容易被访问者访问。
作为额外的奖励，我们得以加强并将文档讨论进一步融入到开发者社区中。 在随后的会议日中，我们不断听到错过会议或不知道会议的参会者表示他们有多遗憾，因为他们本可以使用我们的帮助。 也许文档展位或帮助台可以成为开发者活动的新传统？
开发者活动中的文档讲座
一位作家在开发者大会上做文档讲座。 这不是一个糟糕笑话的开头，而是我很高兴看到增长并且希望看到更多的事情。 开发者在开发者大会上做文档讲座 当然也是非常可以接受和鼓励的； 重要的是以一种吸引开发者受众的方式呈现您的主题。
文档讲座在大会上乍一看可能对开发者参会者没有吸引力，但它们是凝练信息和推销想法的好方法，至少可以让开发者以不同的方式思考文档。 我目前最喜欢的讲座是 FOSS DOCS 101，因为它涵盖了高层次的概念，旨在让开源开发者参与到文档工作中。
文档活动
技术传播会议吹嘘 12 个关于单源主题的讲座，但在现场却看不到一个开发者的日子已经一去不复返了。 新一代文档社区正在兴起，这要归功于基层协作和勇敢实验的开源理念。
Write the Docs，我很荣幸参与其中，它在两年多前在俄勒冈州波特兰市作为一个一次性活动开始，从那时起，它扩展到包括两个国际会议以及美国各地无数的聚会。 它的使命：通过创建一个欢迎所有技术角色讨论与内容相关的任何事情的空间，将文档集成到更广泛的技术社区中，而不是将文档隔离。 事实上，他们会议的与会者中超过 50% 不是作家，而是代表许多开源技术和社区。
另一个值得一提的年度活动是 Open Help，它更侧重于冲刺和公开讨论。 Open Help 邀请所有开源项目聚集在一起，集思广益、黑客和协作处理他们的内容，并在活动中穿插预先选定的演示文稿，以激发讨论并激励与会者。 不，您也不必成为作家才能参加此活动。 唯一的先决条件是关心内容和开源。
点燃变革，鼓励协作
如果没有人将我谈论的所有这些想法付诸实践，那么它们都是无用的。 一个人能做的只有这么多，所以我呼吁你们，开发人员和作家，都伸出手来创造一个协作环境。
如果您是一名作家，请不要害怕向开发者活动提交文档演示文稿、冲刺或研讨会。 您有专业知识可以分享，开发人员会很乐意向您学习经验。 自我第一次涉足开源世界以来，我看到开发者大会、聚会和冲刺中对文档人员的态度有所改善，这要归功于公开讨论，我们作家可以在弥合知识和参与差距方面尽自己的一份力量。
如果您是一名开发人员，请联系文档人员并邀请他们参加您的会议、冲刺和聚会。 参加文档活动，了解作家如何思考、工作和进行社区活动。 每个人都可以从高质量的内容中受益，您会惊讶地发现作家们会多么乐意分享我们积累的知识并帮助开源文档。 我们就在你们中间，你们只需要伸出手。
话题
本文是 Rikki Endsley 协调的 Doc Dish 专栏 的一部分。 要为本专栏投稿，请提交您的故事创意或联系我们。
1 条评论