需要選擇合適的語言來編寫文檔

Question

目前我工作的文檔處於一種狀態。沒有足夠的地方，並且存在的文檔遍佈在許多文檔文檔中，這使得很難找到任何東西。

我試圖採取一些主動，把它提高，我想的第一件事就是找一個更好的格式寫的文檔：

• 我的想法是，該文件的結構應在一系列短文章（MSDN/HTML幫助風格）和結構化的適地適樹的：
  • 這將是很好的能夠產生一個獨立的HTML的幫助風格封裝與應用
  • 運以及能夠產生MSDN風格的我們作爲懶惰看CD的人的參考。
  • 搜索當然是必須具備的
• 它需要至少相當容易更新 - 如果有一個17步驟來更新發布的文檔，然後它使得它看起來像太多的工作做簡單的改變，並且沒有人能夠更新它。
• 該文檔本質上是技術性的，因此理想情況下能夠包含來自嵌入在C＃代碼中的Xml文檔等內容的生成文檔將會很好。然而，這絕對是一個側面要求 - 目前Xml文檔很少有用，只是在將來我打算解決這個問題。
• 出於同樣的原因，能夠處理諸如附件（代碼示例等等）這樣的東西通常是件好事。我並不期待任何幻想，但這是我需要牢記的事情，以確保它至少處理得不好。

是否有任何項目或語言適合這種文檔？

Answer 1

我已經開始使用DokuWiki。它不完全是我最初尋找的東西（我認爲我真的在尋找一個CMS），但它完成了這項工作，並且有些方面比我原先想的要好（特別是它的wiki - 我還沒有得到儘可能發佈到我們的客戶，但我不知道這是多麼好這將解決）

我使用的插件和Arctic模板來獲取左側的導航樹，如果我發佈了wiki本身，我將使用discussion plugin來允許用戶發佈反饋。

目前，我處理生成內容的方法是使用xslt模板生成dokuwiki語法，並將該輸出直接寫入「data/pages」文件夾中的文件/文件夾。

Answer 2

如果您使用的是LaTeX，您可以使用精美的PDF和打印副本獲得所有文檔，並且可以生成html（通過latex2html）。 TeX的優勢在於它也是全明文，因此您可以使用您最喜愛的版本控制系統可靠地跟蹤/合併它。

Answer 3

我們使用confluence作爲我們的文檔庫。公共和私人部分相當容易，並且有一個很好的所見即所得的編輯器。它可以處理附件，並可以保存爲PDF文檔，如果你喜歡。

Answer 4

我已經在我的C和C++項目中使用doxygen獲得了很好的結果，儘管它也支持許多其他語言。您可以將代碼中的文檔放在代碼中，這些代碼可以是簡單或複雜的HTML標記。因爲它是代碼的一部分，所以更新非常容易。您可以將文檔構建爲構建過程的一部分。其他不嚴格與API相關的主題可以添加爲單獨的HTML文檔。我使用的版本不支持搜索，因此您必須添加其他產品才能搜索這些網頁。因爲它是HTML，你可以添加代碼示例，圖表等。

Answer 5

我已經使用robohelp，效果不錯。它是純html，但有一個生成過程，保持翻譯看起來一致。它可以打包成應用程序的.hlp文件，或者發佈到網站上。檢查一下，它很簡單，所以你可以回去做你的工作:)

Answer 6

一個乾淨的方法是使用DocBook。這很容易寫和不被看重。由於XML解析器是標準的，而且其他形式的文檔（例如來自注釋中的嵌入式文檔）可以很容易地轉換爲這種格式，所以也很容易解析。

直接從DocBook源生成PDF，HTML或其他格式（爲此目的而存在工具）。