word文档保存发生错误
关于社区建设 ， 参与和保留的文字很多。 关于社区管理的讨论是活跃而活跃的，到处都有关于如何发展，支持而不破坏开源社区的文章和博客文章。
正如我在先前有关内容策略和文档的DevOps的文章中所提到的那样，高质量的内容非常重要，不仅对用户有价值，而且对贡献者也很有价值。 如果好的文档可以帮助新用户学习您的软件，那么它可以帮助新的贡献者参与您的项目，对吗？
对。 除非关键时刻到来，否则如果社区不参与，所有内容策略和DevOps都不会对您的项目文档有所帮助。 当一些开发人员对某些无法正常工作的事物感到厌倦，或者对制作新事物感到兴奋时，他们便冲入城堡并实现了它。 但是不知何故，《 How to Storm a Castle》教程无处可寻。
要记录还是不记录？
面对这个问题，有多少开发人员说过这些（或类似的）单词？
“我没有时间记录下来。”
“这是自我记录。”
几周或几个月后快进...
“此代码没有文档！”
“这段代码甚至还能做什么？”
“我应该记录下来的……”
你不是一个人。 话是工作。 有时它们比代码更难工作，因为它们不能整齐地编译成二进制文件。 但是它们并不像您想的那么难。
帮助您的社区自助
有很多方法可以改善社区文档，并且项目中的每个人都需要做一些事情，无论他们的角色或经验水平如何。 无论您的项目是刚刚成形还是已经运行多年，花时间改进贡献者编写和发布文档的方式都意味着您的贡献者可以更独立，更轻松地遵循此过程。
要记住的主要事情是，这些工作需要协作，可伸缩和简单。 现在，我将尝试描述一些我已经从开源社区中看到或参与过的活动的示例，这些活动旨在增加开源项目在更好的文档中的参与度，并弥合作者与工程师之间的知识鸿沟。
文档指南
如果代码贡献准则旨在帮助开发人员入门并遵守标准，则文档贡献准则可达到相同的目的。 文档指南可以包括样式约定，有关如何提交文档补丁的过程以及哪些代码贡献需要文档的内容。
贡献文档准则的唯一前提是成功贡献一些东西。 下次在项目中处理文档任务时，为什么不写一些注释或建议并与社区分享呢？ 仅仅开始讨论将文档集成到项目中的最佳方法，这会提醒人们这是一个值得讨论的话题。
需要灵感吗？ 请查看Django ， OpenStack ， KDE和ArchLinux之类的项目，以获取一些文档指南示例。
请记住，文档提交的风险通常比代码提交的风险低。 您应尽可能简化流程，并记住使说明清晰简洁。 如果我需要创建三个不同的用户帐户并获得四个不同的业力积分来解决拼写错误，那么与我说“ Gerrit”相比，您脱离我的速度会更快。
范本
模板非常适合标准化或模块化文档。 以README文件为例。 每个开源项目都以README文件开头，这使它成为非常可见且重要的第一印象文档。
在Pythonista中，“ 阅读文档自述”模板已成为相当一段时间以来的标准。 Drupal项目还具有一个带有章节描述的README模板， Fedora文档团队一直在研究主题为“食谱”的文档手册 ，该手册不仅描述了如何撰写文档和编写指南，而且还可以用作模板。
没有时间制作模板？ 那么一些例子呢！ 您可以选择感觉良好的结构和格式的主题或内容文件，并将其包含在新的文档指南中作为示例。 任何希望提供帮助的人都可以查看源文件，至少可以了解有关如何组织主题以及应包括哪些部分的基本思想。
Doc冲刺，hackfest和研讨会
作为一名作家，这些可能是我最喜欢的活动，因为它们涉及到与开源项目的直接交互，并且经常导致立竿见影的可重复结果。 将开发人员的深入知识与技术作家的软件整体方法相结合，可以带来不仅是文档，而且是项目整体可用性的真正有价值的见解。
我很高兴与Fedora和NixOS等项目一起冲刺，还为KDE （过去）和Django （未来）举办了文档研讨会。 这些冲刺和研讨会帮助我学习了开源文档的内部工作，例如，在NixOS的情况下，导致了四本主要手册中的三本对源文件的完整重组以及新的内容贡献程序 。
Doc sprint也是向您的项目介绍新的贡献者，以及向一般开源的新人介绍的好方法。 在我参与的每个Django Girls研讨会中，我都确保包括该教程的后续文档sprint ，组织者手册以及该程序的任何其他资源。 这是将新手介绍给现实生活中的GitHub贡献工作流程的绝妙方法，同时可以改善文档！
服务台和摊位
最近，我很荣幸能够在开发人员会议（该会议是EuroPython 2015 ）上领导有史以来的第一个（我认为？如果我错了，请纠正我）文档帮助台。 我与Paul Roeland和Maciej Szlosarczyk合作，为我们戴上了医生的帽子和长袍，并开设了一个弹出文档诊所，以满足您所有生病的开源文档需求。
在三小时到四小时的会议中，我们咨询了大约15至20个项目的人们，他们遇到了非常有趣的问题和问题，例如如何重组文档集，从传统文字处理软件创建迁移计划。标记语言和源代码控制，甚至重组项目网站以使文档更易于访问者访问。
另外，我们必须加强文档讨论并将其进一步集成到开发人员社区中。 在接下来的会议日里，我们不断听到未参加会议或不知道会议与会者感到遗憾的与会者，因为他们本可以使用我们的帮助。 在开发人员活动中，文档展位或服务台可能会成为新的传统吗？
开发人员活动中的文档讨论
一位作家在开发者大会上发表了文档演讲。 这不是开玩笑的开始，而是我很高兴看到这种情况在增加，并且希望看到更多。 当然，在开发者大会上进行文档演讲的开发者也是完全可以接受和鼓励的。 重要的是要以吸引开发人员受众的方式介绍您的主题。
会议上的Doc演讲乍一看对开发人员来说似乎没有吸引力，但是它们是浓缩信息和提出想法的一种好方法，至少可以使开发人员以不同的方式考虑文档。 我当前最喜欢的演讲是FOSS DOCS 101 ，因为它涵盖了高级概念，旨在吸引开源开发人员参与文档工作。
文档活动
TechComm会议吹嘘关于单一来源的12场演讲的日子已经一去不复返了，没有一个开发人员可以在现场被发现。 得益于基层协作的开源哲学和勇敢的试验，新一代文档社区越来越受青睐。
我很自豪地参与编写文档 ，该文档是两年前在俄勒冈州波特兰市举办的一次性活动，从那时起开始传播，涵盖了两次国际会议以及在美国各地举行的无数聚会。 ：通过创建一个欢迎所有技术角色讨论与内容相关的内容的空间，将文档集成（而不是隔离）到更广泛的技术社区中。 实际上，参加会议的与会者中有50％以上不是作家，他们代表了许多开源技术和社区。
另一个值得一提的年度活动是Open Help ，它更多地关注冲刺和公开讨论。 Open Help邀请所有开放源代码项目在其内容上进行集体讨论，集思广益，修改和协作，并将活动与预选的演示文稿结合在一起，以激发讨论并激发参与者的兴趣。 不，您也不必成为作家即可参加此活动。 唯一的先决条件是关心内容和开源。
激发变化，鼓励合作
如果没有人付诸实践，我正在谈论的所有这些想法都是无用的。 一个人只能做很多事情，所以我在呼吁您（无论开发人员还是作家）都可以接触并创建协作环境。
如果您是一名作家，请不要害怕向开发者活动提交文档演示，冲刺或研讨会。 您拥有共享的专业知识，开发人员将很高兴从您的经验中学习。 自从我第一次涉足开源世界以来，我就已经在开发人员会议，聚会和sprint中对医生们的态度有所改善，这要归功于公开讨论，我们的作家可以在缩小知识和参与度方面做出自己的贡献。
如果您是开发人员，请与文档人员联系，并邀请他们参加会议，冲刺和聚会。 参加文档活动，并了解作家的想法，工作和社区活动。 每个人都可以从高质量的内容中受益，而您会感到惊讶的是，作家们将多么高兴地分享我们积累的知识，并为开源文档提供帮助。 我们在你们中间行走，您需要做的就是伸出手。
碟
本文是Rikki Endsley协调的Doc Dish专栏的一部分。 要撰写本专栏文章，请提交您的故事创意或与我们联系 。
翻译自: https://opensource.com/business/15/8/docs-or-it-didnt-happen
word文档保存发生错误
3万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
