如何管理開放源代碼軟件的社區文檔

Question

任何人都可以就如何在編寫api文檔中管理開放源代碼軟件開發人員社區提供建議或指出任何指南嗎？

對於大多數項目來說，一個典型的，非託管的起點是有一個項目wiki，任何人都可以自由創建頁面，向現有頁面添加內容，編輯現有內容等。問題是，儘管人們的意圖最好，wiki很容易就會變得混亂，寫得不好，不完整，寫在不同的聲音等等等等。

那麼，怎樣才能提高文檔的質量呢？

我懷疑一個關鍵因素是明確的編輯/風格指南，類似於http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone。任何人都可以指出一個專門針對軟件apis量身定製的指南嗎？

有沒有其他的做法，人們發現有用？例如。形成一個由編輯組成的核心團隊，並且接受社區添加的大多數文檔很可能需要進行「強烈編輯」？

Answer 1

簡而言之，解決方案是社交/人力，而不是技術。爲任何項目獲得良好文檔的方法是讓有時間的人，負責爲文檔組織高級組織，然後參與開發和用戶社區，以確保文檔保持最新並繼續處理用戶通常會遇到的問題和困惑。

社區項目已經接受了你需要一點的人（即「經理人」，對於喜歡「翻譯」和「釋放」的項目方面和各種組件。同樣的事情需要發生相關文檔。

至於工具，Sphinx雖然不是「wiki like」，但它確實很棒，您可以使用任何版本控制系統來存儲文檔，並配置Web服務器以在提交/更新/推送後重建文檔。對於我曾經工作過的任何項目，一直很好。