技術寫作的版本控制

Question

我一直在包括此處在內的其他地方尋找答案，但無濟於事，或者由於我缺乏版本控制經驗而無法看到答案（對不起，請問無知）。

我正在一個技術作家團隊中工作，我們正在處理的文檔由典型的可重用部分組成（例如，描述在多個應用程序中使用的GUI元素）。 當這樣的GUI元素更新到較新的版本並且更改影響多個文檔時，就會出現問題。 有沒有一種方法可以根據一組組成部分自動檢查所有文檔，以查看有關這些組成部分的文檔是否是最新的？

Answer 1

您所描述的不是我認為的版本控制問題。

以此類推，如果程序使用算法並且算法已更新，則我們不使用版本控制來檢測使用該算法的所有場所是否都是最新的。 取而代之的是，我們使用DRY（不要重復自己）等原理以及促進這些原理的工具來構建軟件。

如果您可以在允許您執行鏈接圖像（而不是嵌入圖像）之類的環境中創建軟件，則可能會有所幫助。 順便說一句，一個提供了這種功能的好的文檔管理包可能也具有比git提供的版本控制功能更適合技術文檔需求的版本控制功能。

Answer 2

我知道您為什么要考慮“版本控制”，但是我同意其他答案，這不是版本控制問題。

我認為您正在尋找通常被稱為“包含功能”的東西：您有N個文檔引用相同的GUI元素：與其重復N次與該GUI相關的更改，您只需進行一次更改，然后N個文檔將“包括”描述GUI的文檔。

例如，asciidoctor是一種輕量級但功能強大的文檔標記系統，具有包含這一概念。 （許多其他系統都具有此功能）。

有關示例，請參見此博客文章 。 它指的是包括部分代碼，但是相同的概念可以用於包括部分文本和圖像。

有關更多信息，請參見http://asciidoctor.org 。