Doc as Code (3)：業内人士的觀點

作者 | Anne-Sophie Lardet

在技術傳播國際會議十周年之際，Fluid Topics 的認證技術傳播者和功能顧問 Gaspard上台探讨了“docOps 作為實作Doc as Code的中間結構”的概念。在他的演講中，觀衆提出了幾個問題，我們想分享Gaspard的見解！

首先，讓我們從Doc as Code的介紹開始。

- 1 -

什麼是Doc as Code

Doc as Code是應用軟體開發流程和工具來傳遞技術文檔。它使用與開發團隊相同的工作流程和工具，包括版本控制系統、自動化測試、問題跟蹤器等。它還依賴于輕量級檔案的生産和管理。

Doc as Code相當容易獲得且易于使用。 需要的工具是極簡的，通常是免費的，并且像文本編輯器一樣簡單。Markdown 或 AsciiDoc 等輕量級格式是開始使用Doc as Code的最快方法，因為它們都可以處理純文字檔案。

與任何技術範例一樣，Doc as Code有其優點和缺點。

優點

• 它促進TW和開發人員之間的合作
• 您可以使用與開發人員相同的工具
• 它讓開發人員一起參與文檔生産制作
• 它降低了軟體許可和支援服務的總體成本

缺點

• 需要更深的技術知識
• 最适合軟體産品的文檔

許多機構和公司已轉向Doc as Code作為他們的文檔流程。英國政府的技術文檔團隊使用Doc as Code來提供服務和平台。Spotify、Cloudfare、Kubernetes、Twitch、Arundo、Netflix裝置，甚至Bitcoin等公司都使用靜态站點生成器（SSG）Jekyll，這是Doc as Code場景最常見的釋出工具之一。

- 2 -

與DITA可能存在哪些互動?

Doc as Code和DITA的基本原理是不同的，但兩者可以共存。

2019年6月，Heretto聯合創始人兼首席執行官Patrick Bosek發表了《和睦相處：DITA和Markdown》。他做了如下類比：

Markdown就像一把鏟子，DITA就像一台挖土機。有些人從未使用過挖土機，認為它太複雜了。然後，建造大型建築的建築勞工說：你不能用鏟子建造大型建築。如果你一個人開始一個項目，卻不知道如何操作挖土機，那麼鏟子似乎是顯而易見的選擇。他們倆在世界上都有一席之地，任何建築工地都會有鏟子和挖土機。

Bosek強調了這樣一個事實，即每個文檔标準都有其優勢，我們應該利用每一個标準的長處。

DITA和Doc as Code常用的格式之間存在潛在的聯系。

• 輕量級DITA

您可以使用輕量級DITA來彌合結構化内容和連續文檔之間的差距，輕量級DITA是DITA的簡化版本，使用DITA元素類型、屬性、内容模型的子集和簡化的功能子集。輕量級DITA旨在結合HTML5（HDITA）和Markdown（MDITA），它不是為了取代DITA。它主要針對那些将不懂DITA的員工融入文檔組織。它允許作者跨不同的部門來進行編輯、協作或釋出。

• DITA輔助編輯模式

當有良好使用者體驗的界面提供支援時（即：有好用的編輯器），利用 XML 的好處可能是有意義的。随着文檔化自動化技術向最終使用者友好界面發展，開發人員可能需要通路專門的編輯和管理環境。有一些解決方案可以幫助生成一緻的DITA，如Oxygen XML、IXIASOFT、Heretto、DitaToo、Composize等。

- 3 -

可以添加中繼資料嗎？

有些内容需要比其他内容有更多的語義。在DITA系統中，有不同的方法可以在Topic或Map級别聲明和添加中繼資料。不幸的是，使用Markdown，雖然可以調整現有内容并添加中繼資料，但沒有像DITA那樣提供語義化。以下是一些如何做到這一點的提示：

• 使用YAML檔案将中繼資料與模闆語言相結合
• 利用Markdown檔案的header或為每個相關目錄建立一個README檔案
• 使用Markdown特定風格，如Kramdown，它向内聯元素添加類和ID
• 将帶有class屬性的HTML标簽與Markdown内容結合起來
• 利用類似AsciiDocsy的SSG，它使用内聯語義。
• 例如：.term, .cite, .cmd, .code, .gui, .path, .case和.tip

- 4 -

是否僅限于軟體行業？

Doc as Code确實适合很多公司，但通常仍與軟體開發有關。

重工業在編制技術檔案時使用有限制力的規範，如航空、航天、海軍、核能和鐵路的S1000D标準。有一些特定的要求和時間表與軟體行業不同，是以Doc as Code很難應用。

另一方面，Doc as Code作為一個全球的環境可能适用于不同的内容來源、知識庫、教育内容，甚至依賴聊天機器人的技術。

- 5 -

給初次嘗試團隊的建議

• 循序漸進，從試點開始，熟悉版本控制系統和協作工作流
• 提升TW的GIT技能
• 促進技術文檔團隊和開發人員之間的溝通，讓他們參與到文檔流程中，并幫助他們确定工作的優先級
• 花點時間選擇和評估用于釋出的現有解決方案（如靜态站點生成器）是否符合您的需求
• 為每個存儲庫建立一個README檔案，以了解項目範圍、所需資源、原則和指南
• 開發模闆，實施樣式指南，代碼檢查，并考慮将其內建到CI/CD管道中
• 比較Markdown的不同風格，并考慮使用AsciiDoc甚至輕量級DITA進行創作
• 随時了解專業社群共享的文章、研讨會和資源：
• Write the docs：
• https://www.writethedocs.org/
• Tom Johnson：
• https://idratherbewriting.com/
• Anne Gentle：
• https://justwriteclick.com/
• Brian Dominick：
• https://github.com/briandominick

英文原文位址： https://www.fluidtopics.com/blog/tech-talk/an-insiders-look-at-docs-as-code/