Documentation structure and template

原文：https://docs.gitlab.com/ee/development/documentation/structure.html

Documentation structure and template

本文档将帮助您确定如何在 GitLab 文档中构建页面以及包含哪些内容. 这些标准有助于确保整个文档的一致性和完整性，并使它们的贡献更加容易.

在开始之前，请熟悉GitLab 的文档指南和样式指南中有关内容的部分.

Components of a documentation page

大多数页面将专用于 GitLab 的特定功能或涉及一个或多个功能的用例（可能与第三方工具结合使用）.

每个功能部件或用例文档应按以下顺序包括以下内容，以下内容和此页面中包含的模板中注明了例外和详细信息.

  • 标题 ：具有功能名称或用例名称的顶级标题，该名称应以动词开头，例如” Configure”，” Enable”等.
  • 简介 ：关于此主题以及在此页面上可以找到的内容的简短句子. 描述功能或主题是什么，它做什么，以及在什么情况下应使用它. 无需添加称为”简介”或”概述”的标题，因为人们很少搜索这些术语. 只需将这些信息放在标题之后即可.
  • 用例 ：描述该功能/配置的实际用例场景.
  • 要求 ：描述所需的软件，配置，帐户或知识.
  • 说明 ：遵循一套或多套详细说明.
  • 故障排除指南（推荐但不是必需的）.

有关每个文档的更多详细信息，请参见下面的新文档模板 .

请注意，您可以酌情包括其他小节，例如”工作原理”，”体系结构”以及其他逻辑划分，例如部署前和部署后步骤.

Template for new docs

要开始新文档，请遵守文件树和文件名准则以及样式准则. 使用以下模板：

  1. <!--Follow the Style Guide when working on this document. https://docs.gitlab.com/ee/development/documentation/styleguide.html
  2. When done, remove all of this commented-out text, except a commented-out Troubleshooting section,
  3. which, if empty, can be left in place to encourage future use.-->
  4. --- description: "Short document description." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here.
  5. stage: "Add the stage name here, and remove the quotation marks"
  6. group: "Add the group name here, and remove the quotation marks"
  7. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
  8. --- 
  9. # Feature Name or Use Case Name **[TIER]** (1)
  10. <!--If writing about a use case, drop the tier, and start with a verb, e.g. "Configure", "Implement", + the goal/scenario-->
  12. <!--For pages on newly introduced features, add the following line. If only some aspects of the feature have been introduced, specify what parts of the feature.-->
  13. > [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2).
  15. An introduction -- without its own additional header -- goes here.
  16. Offer a description of the feature or use case, and what to expect on this page.
  17. (You can reuse this content, or part of it, for the front matter's `description` at the top of this file).
  19. The introduction should answer the following questions:
  20.  - What is this feature or use case?
  21. - Who is it for?
  22. - What is the context in which it is used and are there any prerequisites/requirements?
  23. - What can the audience do with this? (Be sure to consider all applicable audiences, like GitLab admin and developer-user.)
  24. - What are the benefits to using this over any alternatives?
  26. ## Use cases
  28. Describe some use cases, typically in bulleted form. Include real-life examples for each.
  30. If the page itself is dedicated to a use case, this section can usually include more specific scenarios
  31. for use (e.g. variations on the main use case), but if that's not applicable, the section can be omitted.
  33. Examples of use cases on feature pages:
  34. - CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
  35. - CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
  36. - EE-only: [Geo](../../administration/geo/replication/index.md)
  37. - EE-only: [Jenkins integration](../../integration/jenkins.md)
  39. ## Requirements
  41. State any requirements for using the feature and/or following along with the instructions.
  43. These can include both:
  44. - technical requirements (e.g. an account on a third party service, an amount of storage space, prior configuration of another feature)
  45. - prerequisite knowledge (e.g. familiarity with certain GitLab features, cloud technologies)
  47. Link each one to an appropriate place for more information.
  49. ## Instructions
  51. "Instructions" is usually not the name of the heading.
  52. This is the part of the document where you can include one or more sets of instructions, each to accomplish a specific task.
  53. Headers should describe the task the reader will achieve by following the instructions within, typically starting with a verb.
  54. Larger instruction sets may have subsections covering specific phases of the process.
  55. Where appropriate, provide examples of code or configuration files to better clarify intended usage.
  56.  - Write a step-by-step guide, with no gaps between the steps.
  57. - Include example code or configurations as part of the relevant step. Use appropriate Markdown to [wrap code blocks with syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting).
  58. - Start with an h2 (`##`), break complex steps into small steps using
  59. subheadings h3 > h4 > h5 > h6\. _Never skip a hierarchy level, such
  60. as h2 > h4_, as it will break the TOC and may affect the breadcrumbs.
  61. - Use short and descriptive headings (up to ~50 chars). You can use one
  62. single heading like `## Configure X` for instructions when the feature
  63. is simple and the document is short.
  65. <!-- ## Troubleshooting
  67. Include any troubleshooting steps that you can foresee. If you know beforehand what issues
  68. one might have when setting this up, or when something is changed, or on upgrading, it's
  69. important to describe those, too. Think of things that may go wrong and include them here.
  70. This is important to minimize requests for support, and to avoid doc comments with
  71. questions that you know someone might ask.
  73. Each scenario can be a third-level heading, e.g. `### Getting error message X`.
  74. If you have none to add when creating a doc, leave this section in place
  75. but commented out to help encourage others to add to it in the future. -->
  76.  --- 
  77. Notes:
  78.  - (1): Apply the [tier badges](styleguide.md#product-badges) accordingly
  79. - (2): Apply the correct format for the [GitLab version introducing the feature](styleguide.md#gitlab-versions-and-tiers)

Help and feedback section

通过在文档的开头添加一个键，可以从文档中省略每个文档末尾显示的”帮助和反馈”部分（由！319引入）：

  1. ---
  2. feedback: false
  3. ---

默认为将其保留在此处. 如果要从文档中忽略它，则必须先咨询技术作家.

Disqus

我们还将 docs 站点与 Disqus 集成在一起（由！151引入），使我们的用户可以发表评论.

要仅忽略反馈部分中的评论，请在最前面使用以下键：

  1. ---
  2. comments: false
  3. ---

We are only hiding comments in main index pages, such as the main documentation index, since its content is too broad to comment on. Before omitting Disqus, you must check with a technical writer.

请注意，一旦在前件中添加了” feedback: false ，它将自动省略 Disqus，因此，请勿将两个关​​键字都添加到同一文档中.

Google 跟踪代码管理器会跟踪”反馈”部分中的点击事件. 通过导航至” 行为”>”事件”>”热门事件”>” docs”，可以在 Google Analytics（分析）上查看转化.