淘汰說明文件

隨著 Fuchsia 的發展，我們需要淘汰已淘汰功能的說明文件或過時的說明文件。

建立淘汰時程

移除說明文件前，請務必建立淘汰時程並通知使用者。一般來說，建議在淘汰期 6 個月後移除說明文件。

如要開始淘汰程序並通知使用者，請按照下列步驟操作：

• 在 Markdown 檔案中淘汰文件
• 在導覽中淘汰文件

在 Markdown 檔案中淘汰文件

如要在 Markdown 檔案中將文件標示為已淘汰：

1. 找出開頭為 # 的頁面標題。例如：

   # Deprecating documentation
   

2. 在文件標題下方加入下列 include 陳述式。例如：

   # Deprecating documentation
   
   {% include "fuchsia-src/_common/_deprecation_notice.md" %}
   
   

3. 請向使用者提供淘汰資訊，例如淘汰原因。此外，請一併說明是否有任何新工具或功能，可取代已淘汰的功能。

4. 在導覽中將文件標示為已淘汰。

在導覽中淘汰文件

如要在 _toc.yaml 檔案中將文件標示為已淘汰，請按照下列步驟操作：

1. 找出參照要淘汰文件的 _toc.yaml 檔案。例如：

   - title: "Deprecating documentation"
     path: /docs/contribute/docs/deprecating-docs.md
   

2. 在頁面標題下方，新增 status: deprecated 的鍵/值組合。例如：

   - title: "Deprecating documentation"
     status: deprecated
     path: /docs/contribute/docs/deprecating-docs.md
   

3. 將變更 (文件和目錄淘汰) 提交至 Fuchsia 存放區。

將網頁重新導向至淘汰通知

淘汰時間表結束後，請刪除網頁並重新導向。

如要刪除網頁並重新導向：

1. 搜尋所有參照要移除網頁的連結。例如：

   grep -r "/docs/contribute/docs/deprecating-docs.md" ~/fuchsia/docs/
   

   這會列出所有透過 grep 指令連結至該頁面的文件。

2. 更新或移除說明文件中參照淘汰頁面的連結。

3. 使用 git rm 移除要淘汰的文件。例如：

   git rm docs/contribute/docs/deprecating-docs.md
   

4. 找出參照文件的 _toc.yaml 檔案，並移除已淘汰文件的項目。

5. 確認 doc-checker 通過。執行 fx lint 即可執行 doc-checker：

   fx lint
   

   修正 doc-checker 可能指出的任何問題。

6. 在 /docs/_common/_deprecated-docs.yaml 檔案中，建立從已淘汰頁面重新導向至淘汰通知頁面的規則。此外，請加入註解，列出淘汰功能和淘汰日期。例如：

   # May 13th, 2022
   # Deprecating documentation around deprecation
   - from: /docs/contribute/docs/deprecating-docs.md
     to: /docs/contribute/docs/deprecation-notice.md
   

7. 將變更提交至 Fuchsia 存放區。