gpt4 book ai didi

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

转载 作者:行者123 更新时间:2023-12-02 13:20:33 24 4
gpt4 key购买 nike

任何人都可以就如何管理开源软件开发人员社区编写 API 文档提供建议或提供任何指南吗?

大多数项目的一个典型的、不受管理的起点是拥有一个项目 wiki,任何人都可以在其中自由创建页面、向现有页面添加内容、编辑现有内容等。问题是,尽管人们有最好的意图,但 wiki 可以很容易变得杂乱无章、写得不好、不完整、用不同的声音写等等。

那么,如何提高文档的质量呢?

我怀疑一个关键因素是明确的编辑/风格指南,类似于 http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone 。谁能指出专门针对软件 API 定制的此类指南的示例吗?

人们发现还有其他有用的做法吗?例如。组建核心编辑团队并接受社区添加的大多数文档很可能需要“严格编辑”?

最佳答案

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

社区项目已经接受您需要关键人员(即“经理”,负责项目的“翻译”和“发布”等各个方面以及各种组件。文档也需要发生同样的事情。

至于工具,Sphinx虽然它不是“像 wiki 那样”,但它确实很棒,确切地说,您可以使用您的项目适合的任何版本控制系统来存储文档并配置您的 Web 服务器以在提交/更新/推送后重建文档。对于我参与过的任何项目来说,这总是很好

关于api - 如何管理开源软件的社区文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/9839719/

24 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com