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

Question

在编写api文档的过程中，如何管理开源软件开发人员社区，有没有人能给出建议，或者指出任何指南？

对于大多数项目来说，一个典型的、非托管的起点是拥有一个项目维基，在那里任何人都可以自由地创建页面、向现有页面添加内容、编辑现有内容等。问题是，尽管人们的意图是好的，但维基很容易成为一个组织混乱、写得不好、不完整、用不同声音写成的维基等等。

那么，如何提高文档的质量呢？

我怀疑一个关键因素是清晰的编辑/风格指南，类似于http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone。有谁能举一个专门为软件apis量身定做的这样的指南的例子吗？

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

Answer 1

简短的答案是，解决方案是社会/人的，而不是技术上的。为任何项目获得好的文档的方法是，有时间的人负责文档的高级组织，然后参与开发和用户社区，以确保文档保持最新，并继续解决用户通常具有的问题和困惑。

社区项目已经接受了这样的观点，即您需要点人(即“经理”)来处理项目的各个方面，如“翻译”和“发布”，以及各种组件。同样的事情也需要发生在文档上。

至于工具，Sphinx真的很棒，尽管它不是“维基”式的，确切地说，你可以使用你的项目喜欢的任何版本控制系统来存储文档，并配置你的web服务器在提交/更新/推送之后重新构建文档。对于我工作过的任何项目，它总是工作得很好。