弃用文档

随着 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. 将更改（文档和 TOC 弃用）提交到 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 代码库。