關於開源項目文檔的建議？

我們正在考慮記錄一個剛剛起步的open source project，我希望能提供一些關於良好方法和工具的建議，這些方法對您而言非常合適。此外，作爲開發人員，您是否喜歡在線文檔，基於wiki的文檔，幫助文件或其他？關於開源項目文檔的建議？

2009-02-01 ccook

[Creating Great API Documentation：Tools and Techniques]可能的重複（http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques） – Mark 2014-04-17 13:15:45

這個問題被問了一年之前「重複」 :) – ccook 2014-04-30 19:32:16

鑑於您的應用程序正在使用C＃開發，請查看Doxygen以生成API文檔。它非常強大（它執行標準javadoc樣式成員文檔，但也會生成調用，繼承，文件依賴關係和協作圖）。儘管它的強大功能很容易使用。它可以生成無數種格式的API文檔：HTML，Latex，聯機幫助等。

對於編寫手冊，教程和其他更靈活的文檔類型，請認真考慮設置wiki。我用DokuWiki取得了很大的成功。它支持語法突出顯示，所以對代碼項目很有用。它還具有用戶ACL，這對於開源項目來說非常方便。它也只需要PHP和沒有數據庫。當然，它提供了版本控制等標準wiki功能。

最後，我應該提到trac，這是一個wiki，版本控制，錯誤跟蹤器混合。這絕對值得一看。

來源

2009-02-01 19:07:13 wilsoniya

雖然我沒有真正贊助過任何開源項目，但我做的很多工作都是合作性的。我發現具有適當權限的wiki是人們合作編寫通用文檔的絕佳方式。在我的情況下，他們通常是發展故事 - 我和客戶正在努力創造這些故事。我認爲這也適用於您的項目的協作文檔。

來源

2009-02-01 16:26:09 tvanfosson

聽起來像Sandcastle會很適合你。

來源

2009-02-01 16:42:16 Irwin

我贊成的包羅萬象的方式是使用Wiki。不過，我喜歡從源代碼自動生成文檔的能力。有很多工具，但我特別喜歡SandCastle。它提供了與大多數.NET開發人員應該已經使用過的MSDN文檔相同的樣式，並且似乎您的開源項目是在.NET中構建的。據我所見，支持的最新框架是.NET 2.0。

來源

2009-02-01 17:00:49 user61230

在線文檔總是一個好主意，尤其是當基於Wiki時。它們更容易搜索，有一些歷史記錄可以防止出現錯誤，並且由於它們沒有長時間文檔記錄或手冊的「糖」，所以它們通常較短。但是，必須特別注意文章命名和鏈接。

但是，如果項目代碼的某些部分用作API，那麼必須在代碼中捕獲相關知識，以便那些使用IDE將鼠標懸停在調用機制上的人員可以看到相關知識。知識的本土化是一個很大的問題，人們通常不願意進行上下文切換。如果在函數頭文件中出現了某些內容，它的讀取機會比其他地方出現的機會要高（儘管總體上不是那麼高）。

在編寫函數頭文檔時，關注指令 - 直接影響客戶端的東西。這些可能是必要的（例如，首先調用X）或提供信息（例如，注意X ...）。

來源

2009-02-01 19:13:36 Uri

的Doxygen的API /編程文檔
的Docbook XML/SGML的官方PDF手冊（在線版本HTML提供）
爲用戶創建的東西維基

看到別人如何（大開源項目我的意思是）

但除了維基（其他海報提到）一些official文檔是alw需要結構/準則東西AYS。維基是更多的爲knowledge base的東西恕我直言

來源

2009-02-01 19:52:25 kazanaki

我個人喜歡Sphinx開發人員書面文件，部分原因是它生成的文件有多好。它處理寫在ReST到LaTeX文檔（打印/ PDF）或HTML。

我不會推薦只有使用API文檔工具，如doxygen。這是偉大的，如果這是也用，但它不應該是文檔的唯一形式。

根據您的用戶社區活躍程度，我也建議增加對配方或其他教程維基，它的內容，那麼可以摺疊成間隔使用獅身人面像其餘的文檔。

來源

2009-02-01 20:02:13 Ryan

關於開源項目文檔的建議？

回答

相關問題