# Documentation structure and template > 原文：[https://docs.gitlab.com/ee/development/documentation/structure.html](https://docs.gitlab.com/ee/development/documentation/structure.html) * [Components of a documentation page](#components-of-a-documentation-page) * [Template for new docs](#template-for-new-docs) * [Help and feedback section](#help-and-feedback-section) * [Disqus](#disqus) # Documentation structure and template[](#documentation-structure-and-template "Permalink") 本文檔將幫助您確定如何在 GitLab 文檔中構建頁面以及包含哪些內容. 這些標準有助于確保整個文檔的一致性和完整性，并使它們的貢獻更加容易. 在開始之前，請熟悉[GitLab 的文檔指南](index.html)和[樣式指南中](styleguide.html)有關內容的部分. ## Components of a documentation page[](#components-of-a-documentation-page "Permalink") 大多數頁面將專用于 GitLab 的特定功能或涉及一個或多個功能的用例（可能與第三方工具結合使用）. 每個功能部件或用例文檔應按以下順序包括以下內容，以下內容和此頁面中包含的模板中注明了例外和詳細信息. * **標題** ：具有功能名稱或用例名稱的頂級標題，該名稱應以動詞開頭，例如" Configure"，" Enable"等. * **簡介** ：關于此主題以及在此頁面上可以找到的內容的簡短句子. 描述功能或主題是什么，它做什么，以及在什么情況下應使用它. 無需添加稱為"簡介"或"概述"的標題，因為人們很少搜索這些術語. 只需將這些信息放在標題之后即可. * **用例** ：描述該功能/配置的實際用例場景. * **要求** ：描述所需的軟件，配置，帳戶或知識. * **說明** ：遵循一套或多套詳細說明. * **故障排除**指南（推薦但不是必需的）. 有關每個[文檔的](#template-for-new-docs)更多詳細信息，請參見下面的[新文檔模板](#template-for-new-docs) . 請注意，您可以酌情包括其他小節，例如"工作原理"，"體系結構"以及其他邏輯劃分，例如部署前和部署后步驟. ## Template for new docs[](#template-for-new-docs "Permalink") 要開始新文檔，請遵守文件樹和文件名準則以及樣式準則. 使用以下模板： ``` <!--Follow the Style Guide when working on this document. https://docs.gitlab.com/ee/development/documentation/styleguide.html When done, remove all of this commented-out text, except a commented-out Troubleshooting section, which, if empty, can be left in place to encourage future use.--> --- 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. stage: "Add the stage name here, and remove the quotation marks" group: "Add the group name here, and remove the quotation marks" 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 --- # Feature Name or Use Case Name **[TIER]** (1) <!--If writing about a use case, drop the tier, and start with a verb, e.g. "Configure", "Implement", + the goal/scenario--> <!--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.--> > [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2). An introduction -- without its own additional header -- goes here. Offer a description of the feature or use case, and what to expect on this page. (You can reuse this content, or part of it, for the front matter's `description` at the top of this file). The introduction should answer the following questions: - What is this feature or use case? - Who is it for? - What is the context in which it is used and are there any prerequisites/requirements? - What can the audience do with this? (Be sure to consider all applicable audiences, like GitLab admin and developer-user.) - What are the benefits to using this over any alternatives? ## Use cases Describe some use cases, typically in bulleted form. Include real-life examples for each. If the page itself is dedicated to a use case, this section can usually include more specific scenarios for use (e.g. variations on the main use case), but if that's not applicable, the section can be omitted. Examples of use cases on feature pages: - CE and EE: [Issues](../../user/project/issues/index.md#use-cases) - CE and EE: [Merge Requests](../../user/project/merge_requests/index.md) - EE-only: [Geo](../../administration/geo/replication/index.md) - EE-only: [Jenkins integration](../../integration/jenkins.md) ## Requirements State any requirements for using the feature and/or following along with the instructions. These can include both: - technical requirements (e.g. an account on a third party service, an amount of storage space, prior configuration of another feature) - prerequisite knowledge (e.g. familiarity with certain GitLab features, cloud technologies) Link each one to an appropriate place for more information. ## Instructions "Instructions" is usually not the name of the heading. This is the part of the document where you can include one or more sets of instructions, each to accomplish a specific task. Headers should describe the task the reader will achieve by following the instructions within, typically starting with a verb. Larger instruction sets may have subsections covering specific phases of the process. Where appropriate, provide examples of code or configuration files to better clarify intended usage. - Write a step-by-step guide, with no gaps between the steps. - 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). - Start with an h2 (`##`), break complex steps into small steps using subheadings h3 > h4 > h5 > h6\. _Never skip a hierarchy level, such as h2 > h4_, as it will break the TOC and may affect the breadcrumbs. - Use short and descriptive headings (up to ~50 chars). You can use one single heading like `## Configure X` for instructions when the feature is simple and the document is short. <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's important to describe those, too. Think of things that may go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> --- Notes: - (1): Apply the [tier badges](styleguide.md#product-badges) accordingly - (2): Apply the correct format for the [GitLab version introducing the feature](styleguide.md#gitlab-versions-and-tiers) ``` ## Help and feedback section[](#help-and-feedback-section "Permalink") 通過在文檔的開頭添加一個鍵，可以從文檔中省略每個文檔末尾顯示的"幫助和反饋"部分（由[！319](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319)引入）： ``` --- feedback: false --- ``` 默認為將其保留在此處. 如果要從文檔中忽略它，則必須先咨詢技術作家. ### Disqus[](#disqus "Permalink") 我們還將 docs 站點與 Disqus 集成在一起（由[！151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)引入），使我們的用戶可以發表評論. 要僅忽略反饋部分中的評論，請在最前面使用以下鍵： ``` --- comments: false --- ``` We are only hiding comments in main index pages, such as [the main documentation index](../../README.html), 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（分析）上查看轉化.