如何管理开源软件社区文档？

Question

有人能给出建议或指引，如何管理一群开源软件开发者在编写API文档方面的社区？

大多数项目的典型未经管理的起点是拥有一个项目维基，任何人都可以自由地创建页面、添加内容到现有页面、编辑现有内容等等。问题在于，尽管人们怀着最好的意图，维基很容易变得杂乱无章、写作质量差、不完整、声音不一致等等。

那么，该怎么做才能提高文档的质量呢？

我认为一个关键因素是明确的编辑/风格指南，类似于http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone。有人能指出一个特别针对软件API的指南示例吗？

还有其他人发现有用的实践吗？例如，组建一个核心编辑团队，并接受大多数由社区添加的文档可能需要进行“强力编辑”的事实？

- Damian Helme

Answer 1

简短的回答是，解决方案是社交/人类的，而不是技术性的。任何项目要获得好的文档，关键是需要有一个有时间的人来负责文档的高级组织，并参与到开发和用户社区中，以确保文档始终保持最新并继续解决用户通常遇到的问题和困惑。

社区项目已经接受了您需要针对项目的各个方面（例如“翻译”和“发布”，以及各种组件）设立点人（即“经理”）。文档也需要发生同样的事情。

至于工具，Sphinx非常出色，尽管它不是“wiki式”的，但可以使用您的项目所熟悉的任何版本控制系统来存储文档，并配置您的Web服务器以在提交/更新/推送后重建文档。这种方法对我所处理的任何项目都运行良好。

- tychoish