什麼是存儲軟件文檔的最佳方式？

Question

一個明顯的答案是「一個內部維基」。用於軟件文檔的wiki有哪些優缺點？還有其他建議嗎？你用什麼軟件文檔？

Loren Segal - 遺憾的是，我們不支持任何doc工具來編譯源代碼註釋中的信息，但我同意這將是存儲技術文檔的最佳方式。我的問題是關於各種文檔 - 從系統管理員類型到用戶文檔。

Answer 1

這是一個非常開放的問題，取決於很多因素。一般來說，如果您使用的語言具有良好的文檔生成工具（javadoc，doxygen，MS的C＃內容），那麼您應該將文檔寫在您的方法之上並讓您的工具生成頁面。優點是您可以將文本保留在您的代碼旁邊，這意味着它可以在邏輯上正確的位置進行組織，並且在對方法的行爲進行更改時可以輕鬆進行編輯。

如果您沒有良好的文檔工具支持或無法訪問源代碼，維基百科是不是一個壞主意，但他們是上述的第二選擇。

注：我在這裏只談論代碼文檔。其他工件顯然不能與代碼一起存儲 - 維基是放置這些文檔的好地方。或者，如果您使用某個CMS，則可以簡單地將它們作爲文本/ pdf /任何可通過存儲庫進行編輯的文件提交到某個docs/文件夾中。它的優點是，如果移動存儲庫，它們會保留在存儲庫中，而維基不會（必然）存在。

Answer 2

我的公司使用各種Sharepoint和一個wiki。 Sharepoint用於像需求，演示文稿，合同等特定文檔，而wiki則用作開發人員存儲庫的幫助指南，以便使用內部開發的庫教程。

Answer 3

假設您正在討論代碼文檔與用戶文檔，如果您不需要將代碼文檔分發給組織外的代碼的文檔，承包商或合作伙伴，則內部wiki非常棒。

如果您想分發代碼文檔，Javadoc或DOxygen更合適。

如果您指的是用戶文檔，您可能需要查看DITA。

Answer 4

是的，我們使用wiki，我們也使用Google文檔。我發現Google文檔比我嘗試過的大多數wiki都要好，如果你不需要跟蹤所有的變化，你什麼都不會損失。 Google文檔提供了一個良好的協作框架。

Answer 5

我們目前使用由外部應用程序（PHP + PhpDocumenter）和各種內部維基解析的內聯文檔。有時它是最好的痛苦（主要是因爲只有一個人更新維基或文檔...）

但是，我一直在尋找使用ikiwiki做內部文檔。它與您的源代理系統（包括Git，Subversion，Mercurial，Bazaar，TLA和Monotone）集成，以便您的文檔跟蹤您的項目。它是用Perl編寫的，有一個擴展的插件系統（包括多種標記語言，默認是Markdown）。另外，源代碼管理系統是基於插件的，所以如果你使用的不是立即支持，你可以添加你自己的。用你的首選語言，如果需要的話，因爲它也支持非perl插件。

Answer 6

我開始用一種方法做用戶文檔這些目標的嘗試：

降價/ HTML/JavaScript的/基於文件的相對鏈接的文檔可移植性（可以在本地文件系統中運行，或者你可以扔掉它在Web服務器），截屏的內置處理（交互調整），和開源的情況下，其他人可能希望做的瘋狂的事情的東西。

您的文檔來源是寫在降價，並在瀏覽器運行時通過JavaScript渲染到HTML。

Mandown   -   http://wittman.org/mandown/

Answer 7

«軟件文檔»是一個通用詞。有「最終用戶文檔」，「開發人員文檔」，「質量保證文檔」。第一個通常由合格的技術人員開發。其他的可能是由維基動態形成的，來自源代碼的文檔評論等。所有這些東西的維護過程通常非常複雜，每個軟件公司都遵循自己的方式。但是，所有這些方面都有一個必要的要點：每個代碼提交者，架構師，經理，qa工程師必須存儲安排好的每條信息，這些信息可能對其他人有幫助。如果需要的話，其他人必須密切關注這些碎片存儲和重新排列碎片。所有步驟大大提高改善所有與開發過程相關的活動。

Answer 8

工具很重要，但不要太陷於尋找魔法工具。我找到的工具沒有任何工具具有「使用微型隱形精靈神奇地記錄一切」的複選框。 :-)

維基將正常工作。或Sharepoint。或Google文檔。或者你可以使用SVN倉庫。如果你真的需要，你可以用筆，信紙和文件櫃來做到這一點。 （我真的不建議！）

大重要的關鍵是你需要有買入整個組織。許多商店會發生什麼事情，他們會花費大量時間和金錢來處理像Sharepoint這樣的一些奇特的解決方案，然後每個人都虔誠地使用它兩週左右，然後人們忙於打最新的里程碑，這是最後一個里程碑任何人都會聽到它。

根據您的組織，領域，開發產品的類型等，有幾個解決方案，但這種或那種方式，你需要建立一個系統和使用它。任命一個人的官方文檔沙皇，給他們一個線索，並告訴他們打人頭腦，每當他們說：「哦，是的，我會完成記錄下周......」。如果這是需要的。 :-)

至於工具......我想通過Atlassian的建議Confluence。這是一個很好的wiki，它的設計目的是在企業環境中工作，它有很多漂亮的功能，可定製的功能，它與Atlassian的其他漂亮工具很好地集成在一起，基本上是一個非常穩定的產品。