ドキュメントの構造とテンプレート
この文書は、GitLabのドキュメントの中でどのようにページを構成し、どのような内容を含めるべきかを決めるのに役立ちます。 これらの基準は、ドキュメント全体の一貫性と完全性を保証し、貢献することを容易にします。
始める前に、GitLabのドキュメンテーションガイドラインとスタイルガイドのコンテンツのセクションに慣れてください。
ドキュメントページの構成要素
ほとんどのPagesは、特定のGitLab機能、または1つ以上の機能(サードパーティツールと連携する可能性もある)を含むユースケースに特化しています。
すべての機能またはユースケースの文書には、以下の順序で以下の内容を含める必要があります。ただし、例外や詳細については、下記およびこのページに含まれるテンプレートに記載しています。
- Title (タイトル): 機能名、または、Configuring (構成する)、Enabling (有効にする) などの動詞で始まるユースケース名を含む最上位の見出し。
- はじめに: このページの主題と内容についての2、3の文章。 その機能やトピックが何であるか、それが何をするのか、どのような文脈で使われるべきかを説明します。 Introduction」や「Overview」というタイトルをつける必要はありません。 なぜなら、このような用語で検索されることはほとんどないからです。 タイトルの後にこの情報を書くだけです。
- 使用例:その機能/構成の実際の使用例のシナリオを記述します。
- 要件:どのようなソフトウェア、構成、アカウント、または知識が必要かを説明します。
- 指示:従うべき1組以上の詳細な指示。
- トラブルシューティングガイド(推奨。)
それぞれの詳細については、以下の新しいドキュメントのテンプレートをご覧ください。
必要に応じて、「How it Works」、「Architecture」、およびデプロイ前のステップやデプロイ後のステップなどの論理的な区分など、追加のサブセクションを含めることができることに注意してください。
新しいドキュメントのテンプレート
新しい文書を開始するには、ファイルツリーとファイル名のガイドライン、およびスタイルガイドラインを尊重してください。 以下のテンプレートを使用してください:
<!--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. 'Configuring', 'Implementing', + 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 `## Configuring 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 “セクション(!319で導入)は、そのフロントマターにキーを追加することで、ドキュメントから省略することができます:
---
feedback: false
---
文書から省略したい場合は、事前にテクニカルライターに確認する必要があります。
ディスカス
また、ドキュメントサイトをDisqus(「!」151が導入)とインテグレーションし、ユーザーがコメントを投稿できるようにしました。
フィードバック欄のコメントのみを省略するには、フロントマターで以下のキーを使用します:
---
comments: false
---
私たちがコメントを非表示にしているのは、メインのドキュメント索引のようなメインの索引ページのみです。 Disqusを省略する前に、テクニカルライターに確認する必要があります。
feedback: false
がフロントマターに追加されると、Disqusは自動的に省略されます。したがって、同じドキュメントに両方のキーを追加しないでください。
フィードバックセクションのクリックイベントはGoogle Tag Managerでトラッキングされます。 コンバージョンはGoogle Analyticsの行動 > イベント > トップイベント > docsで確認できます。