ドキュメンテーション・スタイルガイド

この文書では、文法や書式などを含むGitLabドキュメントの標準を定義しています。特定の単語に関するガイドラインは、単語リストを参照してください。

スタイルに関する質問は、イシューやマージリクエストで@tw-style と言ってください。GitLab Slackワークスペースにアクセスできる場合は、#docs-processes チャンネルを使ってください。

GitLabの声

GitLabブランドガイドラインは、より大きな組織で使われる声を定義しています。

その指針に基づき、GitLabドキュメントの音声は簡潔、直接的、正確であるよう努めています。ゴールは、検索やスキャンがしやすい情報を提供することです。

ドキュメントの語り口は、会話的でありながら簡潔であるべきです。

ドキュメントは単一の真実の情報源（SSoT）です。

GitLabドキュメントは、実装、使用、トラブルシューティングに関連するすべての情報のSSoTです。ドキュメントは継続的に進化します。新しい製品や機能に合わせて更新され、分かりやすさ、正確さ、完全性を向上させています。

このポリシーは情報のサイロ化を防ぎ、GitLab製品に関する情報を見つけやすくします。また、ドキュメントにどのような内容を含めるかについての決定にも役立ちます。

トピックの種類

GitLabはトピックタイプを使って製品ドキュメントを整理しています。

トピックタイプは、ユーザーが情報をより素早く消化するのに役立ちます。また、これらのイシューに対処するのにも役立ちます：

  • コンテンツが見つけにくいGitLabのドキュメントは包括的で、有用な情報が大量に含まれています。トピックタイプは繰り返し使えるパターンを作り出し、コンテンツのスキャンや解析を容易にします。
  • コンテンツは投稿者の視点で書かれていることが多い GitLabのドキュメントは様々な貢献者によって書かれています。トピックタイプ (特にタスク) は、ある機能がどのように実装されたかを文書化するのではなく、他の人の役に立つような形式に情報をまとめるのに役立ちます。

ドキュメントファーストの方法論

製品ドキュメントは完全で信頼できるリソースであるべきです。

  • 質問に対する答えがドキュメントにある場合は、情報を言い換えるのではなく、ドキュメントへのリンクを共有してください。
  • GitLab ドキュメンテーションにない情報に遭遇したら、(MR) マージリクエストを作成して、その情報をドキュメントに追加しましょう。そして、その情報を伝えるために MR を共有しましょう。

ドキュメントに反射的に情報を追加すればするほど、ドキュメントは他の人が効率的にタスクを達成したり問題を解決したりするのに役立ちます。

ローカリゼーションのための文書作成

GitLabのドキュメントはローカライズされていませんが、翻訳に役立つガイドラインに従っています。例えば

GitLabの音声は、翻訳を念頭に置いて、明確に、直接的に書くことを指示しています。単語リストとValeのルールは、ローカライゼーションに重要な一貫性を助けます。

Markdown

GitLabのドキュメントはすべてMarkdownで書かれています。

ドキュメントのウェブサイトでは、MarkdownからHTMLへのレンダリングのために、”味付けされた “KramdownエンジンであるGitLab Kramdownを使っています。Kramdownの機能の使用はリンターによって制限されていますので、通常のMarkdownを使用し、リンク先のスタイルガイドのルールに従ってください。Kramdown特有のマークアップ（例えば、{:.class}）は使用できません。

Kramdownの完全なリファレンスはGitLab Markdown Guideをご覧ください。

MarkdownフォーマットはmarkdownlintとValeを使ってテストされています。

MarkdownでのHTML

ハードコードされたHTMLは有効ですが、使用は推奨されません。以下の場合、HTMLは許可されます：

  • Markdownに同等のマークアップがない場合。
  • 高度なテーブルが必要です。
  • 特殊なスタイリングが必要です。
  • テクニカルライターによるレビューと承認者。

Markdownの見出しレベル

各ドキュメンテーションページはレベル1の見出し (#) で始まります。これはページがHTMLにレンダリングされるとき、h1 要素になります。1ページにつきレベル1の見出しは1つだけです。

  • 各サブセクションについて、見出しレベルをインクリメントします。言い換えると、トピックタイトルの前の# 文字数を増やします。
  • H5 (#####) を超える見出しレベルは避けてください。見出しレベルが 5 つ以上必要な場合は、代わりにトピックを新しいページに移動します。H5 を超える見出しレベルは、右サイドバーのナビゲーションには表示されません。
  • レベルをスキップしないでください。例えば ## >####.
  • トピックタイトルの前後に 1 行の空白行を残します。
  • トピックタイトルにコードを使用する場合は、コードがバックスティックで記述されていることを確認してください。

Markdownにおけるバックティック

バックティックは以下の用途に使用します：

  • コードブロック
  • エラーメッセージ。
  • コマンド、パラメータ、ファイル名
  • 値。例えば”名前” テキスト ボックスにtest と入力します。

メタデータ

それぞれのドキュメントのMarkdownページはYAMLフロントマターを含みます。メタデータのすべての値は文字列として扱われ、docsのWebサイトのみに使用されます。

ステージとグループのメタデータ

各ページには、情報ブロックと同様に、属するステージとグループに関連するメタデータが必要です。例えば

---
stage: Example Stage
group: Example Group
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---

メタデータを入力するには、次の情報を含めてください：

  • stage:ページのコンテンツの大部分が属するステージ。
  • group:ページのコンテンツの大半が属するグループ。
  • info:ページのステージとグループに関連するテクニカルライターの見つけ方。

追加メタデータ

各ページには、追加でオプションのメタデータ（default.htmlNanocレイアウトで設定）を設定することができ、定義されている場合はページの上部に表示されます。

非推奨のメタデータ

type metadata パラメータは非推奨ですが、ドキュメントページにはまだ存在 typeします。metadata パラメータとその値はtype 削除 typeすることができます。

TWメタデータの一括更新

CODEOWNERS ファイルには、ファイルと関連するテクニカルライターのリストが含まれています。

マージリクエストにドキュメントが含まれている場合、CODEOWNERS ファイルの情報によって決まります：

  • 承認者] セクションのユーザー リスト。
  • GitLab Bot がコミュニティ貢献者に対して ping を送信するテクニカルライター。

Rake タスクを使ってCODEOWNERS ファイルを更新することができます。

CODEOWNERS ファイルの更新

グループやTWの割り当てが変更された場合は、CODEOWNERS ファイルを更新する必要があります：

  1. 必要であれば、影響を受けるdoc Pagesのステージとグループのメタデータを更新します。変更が多い場合は、このステップを別の MR で行うことができます。
  2. codeowners.rake ファイルを変更内容で更新します。
  3. gitlab リポジトリのルートに移動します。
  4. このコマンドでRakeタスクを実行します：bundle exec rake tw:codeowners
  5. CODEOWNERS ファイルの変更点をレビューしてください。
  6. すべての変更を追加してコミットし、ブランチをorigin にプッシュします。
  7. マージリクエストを作成し、テクニカルライティングマネージャーにレビューしてもらいます。

codeowners.rake ファイルを更新します：

  • 1つのグループに複数のライターを指定するには、ライター名の間にスペースを入れます。ファイルは両方のライターに割り当てられます。

     CodeOwnerRule.new('Group Name', '@writer1 @writer2'),

    • グループ内の異なるライターを異なるディレクトリのドキュメントに割り当てるには、path パラメータを使用してディレクトリを指定します：

       CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }),

      この例では、writer1 が、/doc/user にあるこのグループに関連するファイルのコードオーナーになります。それ以外では、writer2 がコード・オーナーになります。例については、MR 127903を参照してください。

  • ライターが割り当てられていないグループの場合は、ファイルにグループ名を含め、その行をコメントアウトします：

     # CodeOwnerRule.new('Group Name', ''),

対応言語

GitLabドキュメントは明確で理解しやすいものでなければなりません。

  • 不必要な言葉は避けましょう。
  • 明確に、簡潔に、トピックの目的に沿って。
  • アメリカ英語で、アメリカ文法で書きましょう。(British.yml でテスト）。

大文字・小文字の区別

会社としては、小文字を使う傾向があります。

トピックのタイトル

トピックのタイトルには大文字と小文字を使用します。例えば

  • # Use variables to configure pipelines
  • ## Use the To-Do List

UIテキスト

ボタンラベルやメニュー項目など、特定のユーザーインターフェイスのテキストを参照する場合は、ユーザーインターフェイスで表示されるものと同じ大文字を使用します。このコンテンツに関する基準は、パジャマデザインシステムのコンテンツセクションに記載されており、一般的にこのドキュメンテーションスタイルガイドに記載されているものと一致しています。

ユーザーインターフェースのテキストにスタイルの間違いがあると思われる場合は、イシューやMRを作成し、ユーザーインターフェースのテキストの変更を提案してください。

機能名

  • フィーチャー名は通常小文字です。
  • GitLab固有の機能やツールを示す名詞など、大文字と小文字の区別が必要なものもあります。タイトルケースを必要とするフィーチャーは
    • markdownlint設定に固有名詞として追加し、すべてのドキュメントで一貫して適用できるようにします。
    • 単語リストに追加。

単語リストにない用語は、GitLabテクニカルライターにご相談ください。

Featuresページや features.yml 、用語やフレーズの大文字と小文字をデフォルトで一致させないでください。

その他の用語

の名前を大文字にします：

  • GitLab製品の階層名。例えば、GitLab FreeとGitLab Ultimate。(Tested inBadgeCapitalization.yml.).
  • サードパーティの組織、ソフトウェア、製品。例えば、Prometheus、Kubernetes、Git、The Linux Foundationなど。
  • 手法や方法論。例えば、継続的インテグレーション、継続的デプロイ、スクラム、アジャイルなど。

大文字と小文字は、そのエンティティの権威あるソースに記載されているスタイルに従います。例えばGitLab と npm。

偽のユーザー情報

RESTコールやユーザープロファイルなどのエントリにユーザー情報を含める必要があるかもしれません。GitLab ドキュメントでは、本物のユーザー情報やメールアドレスを使わないでください。メールアドレスや名前の場合は、次のようにします：

  • メールアドレス：example.com で終わるメールアドレスを使用してください。
  • 名前：example_username のような文字列を使用してください。または、Sidney Jones 、Zhang Wei、Alex Garciaのように、一般的な姓を持つ多様な、または性別にとらわれない名前を使用してください。

偽のURL

サンプルURLをドキュメントに含める場合は、次のようにします：

  • example.com を使用してください。
  • gitlab.example.com セルフマネージドGitLabインスタンスのみを参照する場合。GitLab SaaSインスタンスにはgitlab.com 。

偽のトークン

cURLを使ったAPIの呼び出しや、CIで使われる変数のデモのためにトークンが必要になる場合があります。トークンが悪用される可能性が低くても、ドキュメントに本物のトークンを使用しないことを強くお勧めします。

これらの偽トークンを例として使うことができます：

トークンの種類トークンの値
個人アクセストークン<your_access_token>
アプリケーションID2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
アプリケーションシークレット04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
CI/CD 変数Li8j-mLUVA3eZYjPfd_H
プロジェクトランナートークンyrnZW46BrtBFqM7xDzE7dddd
共有ランナートークン6Vk7ZsosqQyfreAxXTZr
トリガートークンbe20d8dcc028677c931e04f3871a9b
Webhookシークレットトークン6XhDroRcYPM5by_h-HLY
ヘルスチェックトークンTu7BgjR9qeZTEyRzGG2P

収縮

短縮形は推奨され、特にチュートリアルや説明文書、ユーザーインターフェイスでは、親しみやすくカジュアルなトーンを作り出すことができます。

しかし、いくつかの短縮形は避けるべきです：

短縮形は使用しないでください。物件例代わりに使用
固有名詞と動詞 コンテナレジストリの強力な機能です。 コンテナレジストリは強力な機能です
ネガティブな点を強調するとXとYを一緒にインストールしないでください。XをYと一緒にインストールしないでください。
参考ドキュメント制限を設定しないでください。制限を設けないでください。
エラーメッセージlocalhostへのリクエストは許可されていません。localhostへのリクエストは許可されていません。

所有格

組織名や商品名などの固有名詞には、所有格 ('s) を使わないようにしましょう。

例えば、Docker's CLI の代わりに、the Docker CLI を使います。

詳しくはGoogleドキュメントのスタイルガイドを参照してください。

前置詞

前置詞は必要に応じて文末に使います。前置詞がぶら下がったり、迷子になったりしても問題ありません。例えば

  • 所属しているグループを離れることができます。
  • アクセス権を与えたいユーザーと認証情報を共有します。

これらの構文は他の構文よりもカジュアルです：

  • あなたがメンバーであるグループを去ることができます。
  • アクセス権を与えたいユーザーと認証情報を共有します。

略語

略語を使用する場合は、ページ内で最初に使用するときにスペルアウトしてください。ページ内で複数回綴る必要はありません。

  • タイトルトピックのタイトルに略語を使用するのは、特にその略語が広く使われていない場合は避けましょう。
  • 複数形：頭字語は複数形にしないようにします。たとえば、YAMLs ではなく、YAML files を使用します。どうしても頭字語を複数形にしたい場合は、アポストロフィを使わないでください。例えば、API'sではなく、APIsを使用してください。
  • 所有格：頭字語を所有格にする場合は注意が必要です。可能であれば、頭字語を所有格にしないように文章を書きましょう。どうしても頭字語を所有格にしたい場合は、単語のスペルアウトを検討しましょう。

数字

テキスト中の数字は、0から9までをスペルアウトし、10以上は数字を使用します。詳しくはマイクロソフトのスタイルガイドをご覧ください。

テキスト

  • マークダウンで書く
  • 新しい段落のために空行を挿入します。

  • 異なるマークアップの間に空行を挿入します（例えば、すべての段落、ヘッダー、リストの後など）。例

     ## Header
   
 Paragraph.
   
 - List item 1
 - List item 2

行の長さ

ソースの内容を読みやすくし、より簡単に差分を比較できるようにするために、可能な限り以下のベストプラクティスに従ってください。

  • 長い行は約 100 文字で分割してください。
  • 新しい文章は改行します。

コメント

Markdown内にコメントを埋め込むには、公開時にレンダリングされない標準的なHTMLコメントを使用してください。例

<!-- This is a comment that is not rendered -->

強調

強調するにはイタリック体ではなく太字を使いましょう。GitLabはサンセリフフォントを使用しており、イタリック体のテキストはセリフフォントほど目立ちません。詳しくは、Butterick’s Practical Typographyの太字か斜体かのガイドを参照してください。

初めて用語を紹介するときにはイタリック体を使うことができます。それ以外は太字を使いましょう。

  • 単語やテキストを太字 (**bold**) にする場合は、ダブル・アスタリスク (**) を使用します。
  • イタリック体(_italic_)のテキストにはアンダースコア(_)を使用してください。
  • ブロッククォートには greater than (>) を使用してください。

句読点

句読点については、以下のガイドラインに従ってください。

  • 完全な文はピリオドで終わらせましょう。
  • 3つ以上の項目のリストでは、最後のandまたはorの前に連続（オックスフォード）コンマを使用します。(OxfordComma.ymlでテスト）。

コンテンツの間隔を空ける場合：

  • 文と文の間は1スペースにしてください。(複数のスペースを使用することはSentenceSpacing.yml でテストされています)。
  • 区切りのないスペースは使用しないでください。代わりに標準的なスペースを使用してください。(lint-doc.sh でテスト済み）。
  • インデントにタブを使用しないでください。代わりにスペースを使用してください。Tab キーを押すと、タブの代わりにスペースが出力されるようにコードエディターを設定できます。

これらの句読点は使用しないでください：

  • ; (セミコロン）：代わりに2つの文を使用してください。
  • – (enダッシュ)または— (emダッシュ)：(emダッシュ): 文を分けるか、カンマで区切ってください。
  • “ ” ‘ ’:二重または一重のタイポグラファの引用符。代わりにストレート引用符を使用してください。(NonStandardQuotes.ymlでテスト）。

プレースホルダ・テキスト

コードブロックの中で、特定の値を使用するコマンドや設定を提供したい場合があります。

このような場合、< と> を使用して、読者がテキストを独自の値に置き換える必要がある箇所を呼び出します。

使用例：

cp <your_source_directory> <your_destination_directory>

プレースホルダがコードブロック内にない場合は、< と> を使用し、プレースホルダを1つのバックティックで囲みます。例えば

Select **Grant admin consent for `<application_name>`**.

キーボード・コマンド

キー入力を参照する場合は、HTML<kbd> タグを使用してください。例えば

To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.

ドキュメントが生成されるとき、出力は次のようになります：

コマンドを停止するには、Control+Cを押します。

UIのボタン

ラベルが表示されている要素には、大文字と小文字を一致させた太字のラベルを使用してください。

例えばSelect **Cancel**.

UIに入力されたテキスト

ユーザーがUIに何かを入力する場合、バックスティックを使用します。例えば

In the **Commit message** text box, type `This is my merge request`.

バックティックは引用符よりも正確です。例えば、この文字列では

  • コミットメッセージテキストボックスに“This is my merge request.” と入力してください。

ユーザーが文字列にピリオドを含めるべきかどうかは不明です。

インラインコード

インライン コード スタイルは、通常のテキストとインラインで適用されます。インライン コード スタイルを使用します：

  • 設定フ ァ イ ルの フ ァ イ ル名ま たは フ ラ グ メ ン ト に対 し て。例えば、.gitlab-ci.yml、CODEOWNERS 、only: [main]。
  • HTTP メソッド (HTTP POST) および HTTP ステータス・コード (完全 (404 File Not Found) と省略 (404) の両方)。例えばランナーを削除するには、DELETE リクエストを送信します。ランナーを作成するには、POST リクエストを送信します。

インライン・コード・スタイルを適用するには、テキストを1つのバックスティック (`) で囲みます。例えば、this is inline code style 。

コードブロック

コードブロックスタイルは、コードテキストと通常のテキストを分離します。コマンドラインインターフェイスで実行されるコマンドにはコードブロックスタイルを使用します。コードブロックスタイルは、ユーザーのターミナルウィンドウにコピー＆ペーストしやすくなります。

コードブロックスタイルを適用するには、テキストを三重のバックティック（`）で囲み、構文の強調表示ヒントを追加します。例えば

```plaintext
This is codeblock style
```

コードブロックスタイルを使用する場合：

  • スタイル設定するコードブロックに3重のバックティックがある場合、4重のバックティック（`）を使用してコードブロックスタイルを適用します。例えば、コード・ブロック・スタイルを図示する場合。
  • コードブロックの上下に空白行を追加します。
  • シンタックスハイライトヒントはコードブロックに必要です。利用可能なシンタックス・ハイライトについては、サポートされている言語とレキサーのリストを参照してください。よりよいヒントがない場合はplaintext を使用してください。

コードブロック内のcURLコマンド

cURLコマンドのスタイリングについては、「cURLコマンド」を参照してください。

リスト

  • フレーズが完全な文でない場合は、ピリオドを使用しないでください。
  • すべての文の後にピリオドを使用してください。セミコロンやコンマは使用しないでください。
  • 多数決。すべての項目の句読点は同じにします。
  • リスト項目は大文字で始めてください。

  • 導入フレーズと説明テキストはコロン (:) で区切ります。例えば

     You can:
   
 - Do this thing.
 - Do this other thing.

順序付きリストか順序なしリストのどちらかを選択してください。

順序付きリストは、一連のステップに使用します。例えば

Follow these steps to do something.

1. First, do the first step.
1. Then, do the next step.
1. Finally, do the last step.

ステップを順番に完了する必要がない場合は、順序なしリストを使用します。例えば

These things are imported:

- Thing 1
- Thing 2
- Thing 3

リストのマークアップ

  • 順序なしリストには、アスタリスク (*) の代わりにダッシュ (-) を使ってください。
  • 順序付きリストの各項目は1.で始めます。レンダリング時、リスト項目は連続したものになります。
  • リストの前後には空白行を残してください。
  • ネストされたサブ項目を表すには、行頭にスペース（タブではない）を入れてください。

リスト項目内の入れ子

リスト項目の下に項目を入れ子にすると、リスト項目と同じインデントで表示されます。これを行うには

入れ子になった項目は常にリスト項目の最初の文字に揃えるべきです。順序なしリスト（-を使用）の場合、各レベルのインデントには2つのスペースを使用してください：

- Unordered list item 1

  A line nested using 2 spaces to align with the `U` above.

- Unordered list item 2

  > A quote block that will nest
  > inside list item 2.

- Unordered list item 3

  ```plaintext
  a code block that nests inside list item 3
  ```

- Unordered list item 4

  ![an image that will nest inside list item 4](image.png)

順序付きリストの場合、各レベルのインデントには3つのスペースを使います：

1. Ordered list item 1

   A line nested using 3 spaces to align with the `O` above.

リストを他のリストの中に入れ子にすることができます。

1. Ordered list item one.
1. Ordered list item two.
   - Nested unordered list item one.
   - Nested unordered list item two.
1. Ordered list item three.

- Unordered list item one.
- Unordered list item two.
  1. Nested ordered list item one.
  1. Nested ordered list item two.
- Unordered list item three.

テーブル

表は複雑な情報をわかりやすく記述するために使うべきです。多くの場合、項目のリストを記述するには、1項目につき1つの簡単な説明で済む順序なしリストで十分です。しかし、マトリックスで記述するのが最適なデータがある場合は、テーブルが最適です。

作成ガイドライン

テーブルをアクセスしやすくし、スキャンしやすくするために、テーブルには空のセルを入れてはいけません。セルに意味のある値がない場合は、’not applicable’（該当なし）またはNone（なし）のN/Aを入力してください。

テーブルをメンテナーしやすくするために、次のことができます：

  • 空白を追加して列幅を統一します。例えば

     | App name | Description         | Requirements |
 |----------|---------------------|--------------|
 | App 1    | Description text 1. | A, B, and C. |
 | App 2    | Description text 2. | None         |

  • テーブルの幅が非常に広い場合は、右端の列の追加スペースをスキップします。例えば

     | Setting   | Default | Description |
 |-----------|---------|-------------|
 | Setting 1 | `1000`  | A short description. |
 | Setting 2 | `2000`  | A long description that would make the table too wide and add too much whitespace if every cell in this column was aligned. |
 | Setting 3 | `0`     | Another short description. |

表組みのためのエディター拡張機能

すべてのMarkdownファイルで一貫したテーブルフォーマットを確保するために、VS CodeMarkdown Table Formatterを使用してテーブルをフォーマットすることを検討してください。上記のガイドラインに従うようにこのエクステンションを設定するには、ヘッダー行の長さに従う設定を有効にしてください。設定を有効にするには

  • UI では

    1. VS Codeメニューで、Code > Settings > Settingsと進みます。
    2. Limit Last Column Length を検索します。
    3. Limit Last Column Lengthドロップダウンリストで、Follow header row length を選択します。

  • VSコードsettings.json に、新しい行を追加します：

     {
   "markdown-table-formatter.limitLastColumnLength": "Follow header row length"
 }

この拡張子を持つ表を書式設定するには、表全体を選択し、選択範囲を右クリックして「選択範囲の書式設定」を選択します。

Sublime Textを使用している場合、Markdown Table Formatterプラグインを使用することもできます。

既存のテーブルの更新

既存のテーブルに行を追加または編集すると、新しい行のセルの幅が広くなる場合があります。幅を考慮して列の位置を変更すると、テーブル全体が変更されたように表示されるため、差分が読みにくくなります。

Markdownのテーブルは時間の経過とともに自然に位置がずれていきますが、docs.gitlab.com 。テクニカルライティングチームは、次にページがリファクタリングされたときに、セルを再調整することができます。

テーブルの見出し

表の見出しには文の大文字と小文字を使います。例えば、Keyword value またはProject name 。

特徴的な表

機能の一覧表(権限ページの各ロールで利用可能な機能など)を作成する場合、以下のフレーズを使用してください：

オプションMarkdown表示結果
なし**{dotted-circle}** No {点線円｝いいえ
はい**{check-circle}** Yes {チェックサークル｝はい

API ドキュメントでは**{dotted-circle}** と**{check-circle}** を使用しないでください。代わりに、APIトピックテンプレートに従ってください。

脚注

脚注を示すには、<sup> というHTMLタグと数字を使います。タグは文や用語の最後に付けます。例えば

| App name | Description                    |
|:---------|:-------------------------------|
| App A    | Description text. <sup>1</sup> |
| App B    | Description text. <sup>2</sup> |

表の下の脚注には、HTMLタグ<small> 、<ol> 、<li>を使用します。例えば

<html>
<small>Footnotes:
  <ol>
    <li>This is the footnote.</li>
    <li>This is the other footnote.</li>
  </ol>
</small>
</html>

このテキストはこのように出力されます：

アプリ名説明
アプリA説明テキスト1
アプリB説明テキスト2
脚注
  1. これは脚注です。
  2. これがもう一つの脚注です。

引用

Markdownコンテンツに対してのみ有効です：

  • 標準引用符：二重引用符 (").例「これは二重引用符で囲まれています。
  • 引用符の内部での引用：二重引用符 (") で一重引用符 (') を囲みます。例「この文章は引用符で囲まれています。

その他の句読点ルールについては、パジャマデザインシステムの句読点セクションを参照してください。これは、ドキュメント固有の句読点規則によって上書きされます。

リンクは、ドキュメントが単一真実源原則を遵守するのに役立ちます。

しかし、どのページにもリンクを貼りすぎるのは避けるべきです。多すぎるリンクは読みやすさの妨げになります。

  • 同じページにリンクを重複させないでください。例えば、AページにBページへのリンクを何度も貼らないようにしましょう。
  • 一つの段落に複数のリンクを貼らないようにしましょう。
  • 1つのタスクに複数のリンクを張るのは避けましょう。
  • 1つのページで、他のページへのリンクを15個以上使わないようにしましょう。
  • タスクの流れを妨げるリンクを減らすために、関連トピックの使用を検討してください。
  • 同じページのセクションへのアンカーリンクはなるべく避けましょう。ユーザーに正しいナビゲーションを利用してもらいましょう。

同じリポジトリ内の別のページにリンクするには、相対ファイルパスを使います。たとえば、../user/gitlab_com/index.md.

[Text][identifier] のような参照スタイルのリンクではなく、インラインリンク Markdown マークアップ[Text](https://example.com) を使用してください。

リンターが見つけられるように、リンク全体を1行にまとめてください。

別のリポジトリにあるページにリンクするには、絶対 URL を使います。たとえば、GitLab リポジトリのページから Charts リポジトリにリンクするには、https://docs.gitlab.com/charts/ のような URL を使います。

各トピックのタイトルにはアンカーリンクがあります。たとえば、## This is an example というタイトルのトピックには、#this-is-an-example というアンカーがあります。

ページの最初のトピックタイトル (h1) にはアンカーリンクがありますが、使用しないでください。代わりにページにリンクしてください。

トピックタイトルに商品ティアバッジがある場合は、アンカーリンクに含めないでください。たとえば、トピック## This is an example **(FREE ALL)** の場合は、アンカー#this-is-an-exampleを使用します。

Kramdownでは、HTML要素にカスタムIDを追加できますが、これらのIDは/help では機能しないため、使用しないでください。

トピックのタイトルテキストを変更すると、アンカーリンクも変更されます。リンク切れを防ぐために

  • トピックタイトルにステップ番号を使用しないでください。
  • 可能な限り、将来変更される可能性のある単語は使用しないでください。

トピックのタイトルを変更すると、アンカーリンクも変更されます。関連リンクを確実に更新するには、以下のディレクトリを検索してください：

  • doc/*
  • app/views/*
  • ee/app/views/*

これらのリンクを修正しない場合、マージリクエストのui-docs-lint ジョブ は失敗します。

リンクのテキスト

リンクテキストは以下のガイドラインに従ってください。

標準テキスト

できるだけ、これらのパターンのいずれかに従ったテキストを使用してください：

  • For more information, see [LINK TEXT](LINK).
  • To [DO THIS THING], see [LINK TEXT](LINK)

使用例：

  • For more information, see [merge requests](LINK).
  • To create a review app, see [review apps](LINK).

この文章をさらに発展させるには、次のようなフレーズを使います。For more information about this feature, see...

次の構文は使わないでください：

  • Learn more about...
  • To read more....
  • For more information, see the [Merge requests](LINK) page.
  • For more information, see the [Merge requests](LINK) documentation.

説明的な文章here

リンクには、here のような言葉ではなく、説明的なテキストを使いましょう。this page.

例えば

  • For more information, see [this page](LINK).
  • For more information, go [here](LINK).

使用方法。

  • For more information, see [merge requests](LINK).

イシューにリンクする場合は、リンクにイシュー番号を含めてください。例えば

  • For more information, see [issue 12345](LINK).

ポンド記号 (issue #12345) は使用しないでください。

可能な限り、外部ドキュメントへのリンクは避けてください。このようなリンクは古くなりやすく、メンテナーも難しくなります。

リンクが必要な場合もあります。トラブルシューティングの手順を明確にしたり、コンテンツの重複を防ぐのに役立つかもしれません。より正確で、より積極的にメンテナンスされることもあります。

外部リンクを追加するごとに、顧客の利益とメンテナンスの難しさを天秤にかけてください。

直接リンクしないでください：

これらのリンクは以下の場合に失敗します：

  • 十分な権限がない場合。
  • 自動リンクチェッカー

これらのリンクのいずれかを使用する必要がある場合：

  • リンク先が機密のイシューや内部ハンドブックのページである場合は、そのイシューやページがGitLabのチームメンバーにのみ公開されていることを明記してください。
  • リンクに特定のロールや権限が必要な場合は、その情報を記載してください。
  • リンクチェッカーが失敗しないように、リンクをバックスティックで囲んでください。

例：

GitLab team members can view more information in this confidential issue:
`https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>`

GitLabチームメンバーは、この内部ハンドブックのページで詳細を見ることができます：https://internal.gitlab.com/handbook/<link>

Users with the Maintainer role for the project can use the pipeline editor:
`https://gitlab.com/gitlab-org/gitlab/-/ci/editor`

ファイルの特定の行にリンクする場合は、ブランチではなくコミットにリンクしてください。コードの行は時間とともに変化します。コミットリンクを使用して行にリンクすることで、ユーザーは確実にあなたが参照している行にたどり着きます。プロジェクトのファイルを表示しているときに表示されるPermalinkボタンは、そのファイルの最新のコミットへのリンクを提供します。

  • To-Do：[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)
  • しないでください：[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).

リンクされた式が追加コミットによって行番号が変更された場合でも、そのクエリでファイルを検索することができます。この場合、最新バージョンのファイルにリンクするようにドキュメントを更新してください。

GitLab UI のナビゲーション方法を文書化する場合：

  • 常に location を使い、次に action を使いましょう。
    • 可視性のドロップダウンリスト（場所）から、公開（アクション）を選択します。
  • 簡潔かつ具体的に記述してください。例えば
    • To-Do：保存を選択します。
    • To-Doを選択しないでください：変更を有効にするには、[保存] を選択します。
  • ステップに理由を含める必要がある場合は、ステップをその理由で開始します。こうすることで、ユーザーがより迅速にスキャンできるようになります。
    • -Do：変更を表示するには、マージリクエストでリンクを選択してください。
    • To-Do ではありません：変更を表示するには、マージリクエストでリンクを選択してください。

メニューの名前

GitLabの主要なユーザーインターフェイス要素を指すときは、これらの用語を使います：

  • 左サイドバー: ユーザーインターフェースの左側にあるナビゲーションサイドバーです。
    • context switcher やswitch contexts というフレーズは使わないでください。その代わりに、繰り返し可能な一連のステップで、ユーザーを正確な場所に誘導するようにしてください。
    • the **Explore** menu やthe **Your work** sidebar は使わないでください。代わりにthe left sidebarを使ってください。
  • 右サイドバー: ユーザーインターフェースの右側にある、オープンイシュー、マージリクエスト、エピックに特化したナビゲーションサイドバーです。

UI要素の名前

ボタンやチェックボックスの名前のように、UI要素は太字であるべきです。個々のUI要素のガイダンスは、単語リストにあります。

ナビゲーションタスクステップの書き方

一貫性を保つために、タスクトピックにナビゲーションステップを記述する場合は、以下のテ ンプレートを使用します。

プロジェクトの設定を開くには

1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > CI/CD**.
1. Expand **General pipelines**.

グループの設定を開きます：

1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > CI/CD**.
1. Expand **General pipelines**.

プロジェクト設定とグループ設定のどちらかを開きます：

1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Settings > CI/CD**.
1. Expand **General pipelines**.

プロジェクトを作成します：

1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.

グループを作成します：

1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.

管理エリアを開きます：

1. On the left sidebar, select **Search or go to**.
1. Select **Admin Area**.

Your workメニューを開くには：

1. On the left sidebar, select **Search or go to**.
1. Select **Your work**.

アバターを選択します：

1. On the left sidebar, select your avatar.

ドロップダウンリストの選択を保存します：

1. Go to your issue.
1. On the right sidebar, in the **Iteration** section, select **Edit**.
1. From the dropdown list, select the iteration to associate this issue with.
1. Select any area outside the dropdown list.

すべてのプロジェクトを表示します：

1. On the left sidebar, select **Search or go to**.
1. Select **View all my projects**.

すべてのグループを表示するには：

1. On the left sidebar, select **Search or go to**.
1. Select **View all my groups**.

オプションの手順

ステップがオプションの場合は、Optional の後にピリオドを付けてステップを開始します。

使用例：

1. Optional. Enter a description for the job.

推奨されるステップの場合は、Recommended の後にピリオドを続けます。

使用例：

1. Recommended. Enter a description for the job.

複数のフィールドを一度に文書化

UIテキストがセクションのフィールドを十分に説明する場合、すべてのフィールドのタスクステップを含めないでください。代わりに、複数のフィールドを1つのタスクステップにまとめます。

Complete the fieldsというフレーズを使いましょう。

使用例：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定] > [リポジトリ]を選択します。
  3. プッシュルールを展開します。
  4. 各項目を入力してください。

複数のフィールドを文書化する場合で、説明が必要なフィールドが1つだけの場合は、同じステップで説明してください：

  1. プッシュルールを展開します。
  2. フィールドを入力します。ブランチ名は正規表現でなければなりません。

複数のフィールドを記述するには、順序なしリスト項目を使用してください：

  1. 一般的なパイプラインを拡大する。
  2. 各項目を入力してください。
    • ブランチ名は正規表現でなければなりません。
    • ユーザーは少なくともメンテナーのロールを持つユーザーでなければなりません。

画像

スクリーンショットを含む画像は、読者の理解を深めるのに役立ちます。しかし、画像の使用は控えめにしましょう：

  • 古くなりやすい
  • ローカライズが難しく、コストがかかる
  • スクリーンリーダーでは読めません。

必要な場合は、画像を使って読者の理解を助けてください：

  • 複雑なプロセスのどこにいるのか
  • どのようにアプリケーションと対話するか

画像をキャプチャ

スクリーンショットを撮るとき

  • 価値があることを確認してください。 lorem ipsum テキストは使わないでください。実際のシナリオでその機能がどのように使われるかを再現し、現実的なテキストを使うようにしましょう。
  • 関連するUIのみをキャプチャしてください。不要な余白や、ポイントを説明するのに役に立たないUIの部分を含めないようにしましょう。GitLabのサイドバーは変更されることがあるので、絶対に必要でない限りスクリーンショットに含めないでください。
  • 小さくしましょう。画面の幅いっぱいに表示する必要がない場合は、表示しないでください。ブラウザのウィンドウサイズをできるだけ小さくして、要素を近づけ、余白を減らします。スクリーンショットのサイズはできるだけ小さくしてください。
  • 画像がページ上でどのようにレビュアーされるかをレビューします。画像をローカルでプレビューするか、マージリクエストのレビューアプリを使用してください。画像がぼやけていないか、圧倒されていないか確認してください。
  • 一貫性を保ちましょう。一貫した読書体験のために、ドキュメント・ページに既にある他のスクリーンショットとスクリーンショットを調整してください。ナビゲーションのテーマがIndigoで、シンタックスハイライトのテーマがLightであることを確認してください。これらはデフォルトの設定です。

コールアウトの追加

スクリーンショットで領域を強調する必要がある場合は、矢印を使用します。

  • 色には#EE2604 を使います。MacOSでプレビューアプリケーションを使用する場合、これはデフォルトの赤です。
  • 線幅には 3pt を使用します。macOS のプレビュー・アプリケーションを使用している場合、これはリストの 3 行目になります。
  • 次の画像に示す矢印のスタイルを使用します。
  • 複数の矢印がある場合は、可能な限りParallelsにしてください。

callout example

画像を保存

  • 必要に応じて、幅や高さのあるスクリーンショットのサイズを変更しますが、サイズを変更して圧縮した後もスクリーンショットが鮮明であることを確認してください。
  • 画像はすべて100KB以下に圧縮して ください。多くの場合、画質を落とさずに25～50KB以下にすることが可能です。
  • 画像の特徴やコンセプトを説明する小文字のファイル名で保存してください：
    • image_name_vX_Y.png画像がGitLabインターフェイスのものであれば、ファイル名にGitLabのバージョンを追加します。例えば、GitLab 11.1のパイプラインページから撮ったスクリーンショットの場合、有効な名前はpipelines_v11_1.png です。
    • ユーザーインターフェイスの一部を含まないイラストを追加する場合は、画像が追加されたリリースに対応するリリース番号を追加してください。11.1のマイルストーンに追加されたMRの場合、イラストの有効な名前はdevops_diagram_v11_1.png です。
  • 画像は、作業中の.md ドキュメントがあるのと同じディレクトリのimg/ という別のディレクトリに置きます。
  • JPEGの代わりにPNG画像を使うことを検討してください。
  • https://ezgif.com/optimize 、または同様のツールでGIFを圧縮します。
  • 画像は（必要な場合のみ）プロセスの説明を説明するために使用し、それを置き換えるために使用すべきではありません。
  • ドキュメントを説明するために動画をリンクしたり埋め込んだりする方法も参照してください。

コンテンツに画像リンクを追加

ドキュメントに画像を含めるためのMarkdownコードは以下の通りです：![Image description which will be the alt tag](img/document_image_title_vX_Y.png)

画像の説明はドキュメントサイトでレンダリングされる画像のaltテキストです。アクセシビリティとSEOのために、次のような説明を使用してください：

  • 正確で、簡潔で、ユニークであること。
  • イメージの説明にimage ofや graphic ofを使わないでください。

画像の圧縮

ドキュメントに追加する新しい画像は、必ず圧縮してください。有名なツールのひとつに、クロスプラットフォームでオープンソースのpngquantがあります。公式サイトにアクセスし、あなたのOSに合った指示に従ってインストールしてください。

MacOSを使用していて、すべてのスクリーンショットを自動的に圧縮したい場合は、スクリーンショットを80%小さくする1つの簡単なトリックをお読みください。

GitLabにはRubyスクリプトがあり、これを使えば手動で行う作業を簡略化できます。https://gitlab.com/gitlab-org/gitlab の内部コピーのルートディレクトリで、ターミナルで実行します：

  • 圧縮する前に、必要であれば、すべてのドキュメントのPNG画像が圧縮されていることを確認してください：

     bin/pngquant lint

  • pngquant を使用して、すべてのドキュメント PNG 画像を圧縮します：

     bin/pngquant compress

  • 特定のファイルを圧縮します：

     bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png

  • 特定のディレクトリ内のすべてのPNGファイルを圧縮します：

     bin/pngquant compress doc/user/img

アニメーション画像

アニメーション画像（アニメーションGIFなど）の使用は避けましょう。ユーザーにとって邪魔で迷惑なものになります。

ユーザーインターフェイスの複雑なインタラクションを説明する際に、読者の理解を助けるために視覚的な表現を含めたい場合は、可能です：

  • 静止画像（スクリーンショット）を使用し、必要に応じて吹き出しを追加して、画面の領域を強調します。
  • インタラクションの短いビデオを作成し、それにリンクします。

自動スクリーンショット生成機能

自動スクリーンショットジェネレータを使用すると、スクリーンショットを撮影して圧縮できます。

  1. GitLab Development Kit(GDK) を設定します。
  2. クローンした GitLab リポジトリのあるサブディレクトリ（通常はgdk/gitlab ）に移動します。
  3. GDK データベースが完全にマイグレーションされていることを確認します:bin/rake db:migrate RAILS_ENV=development.
  4. pngquant をインストールします。詳細はツールのウェブサイトを参照してください：pngquant
  5. scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version> を実行してください。
  6. スクリプトのit パラメータで定義されたgitlab/doc の場所に基づいて、スクリーンショットの場所を特定します。
  7. 新しく作成したスクリーンショットをコミットします。

ツールの拡張

スクリーンショット・ジェネレータを追加するには、以下の手順を実行します：

  1. spec/docs_screenshots ディレクトリを探します。
  2. 拡張子_docs.rb の新規ファイルを追加します。

  3. ファイルには必ず以下の情報を記述してください：

    require 'spec_helper'
   
RSpec.describe '<What I am taking screenshots of>', :js do
  include DocsScreenshotHelpers # Helper that enables the screenshots taking mechanism
   
  before do
    page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page
  end

  4. また、it ブロックには、スクリーンショットを保存するパスを含める必要があります：

    it 'user/packages/container_registry/img/project_image_repositories_list'
全ページのスクリーンショット

全ページのスクリーンショットを撮るには、visit the page 、実コンテンツに期待することを実行します（Capybaraにページの準備ができるまで待たせ、白いスクリーンショットを撮らないようにします）。

要素のスクリーンショット

スクリーンショットを撮るには、さらにいくつかのステップが必要です：

  • エリアを見つけるscreenshot_area = find('#js-registry-policies')
  • ピントを合わせた部分をスクロールします：scroll_to screenshot_area
  • コンテンツを待ちます：expect(screenshot_area).to have_content 'Expiration interval'
  • クロップエリアを設定します：set_crop_data(screenshot_area, 20)

特に、set_crop_data は、DOM 要素とパディングを引数として受け取ります。パディングは要素の周りに追加され、スクリーンショット領域を拡大します。

spec/docs_screenshots/container_registry_docs.rb をガイドとして、また独自のスクリプトを作成するための例として使用してください。

絵文字

どんな目的であれ、Markdownの絵文字フォーマット、例えば:smile: は使わないでください。代わりにGitLab SVGアイコンを使ってください。

Markdownで絵文字を使うにはGitLab Flavored Markdownが必要です。これはGitLabドキュメントで使われているMarkdownレンダリングエンジンKramdownではサポートされていません。

GitLab SVGアイコン

GitLab 12.7から導入されました。

GitLab SVGライブラリのアイコンをドキュメントで直接使うことができます。例えば、**{tanuki}** のようにレンダリングされます：.

ほとんどの場合、アイコンをテキストで使うのは避けるべきです。ただし、ホバー・テキストがUI要素を説明する唯一の方法である場合は、アイコンを使用できます。例えば、DeleteボタンやEditボタンは、しばしばホバー・テキストしかありません。

アイコンを使う場合は、ホバーテキストから始め、その後に SVG 参照を括弧で囲んでください。

  • 避けましょう： Select **{pencil}** **Edit**. これは次のように生成されます：鉛筆}を選択してください。編集します。
  • 代わりに使用します： Select **Edit** (**{pencil}**). として生成されます：編集({鉛筆})を選択。

アイコンの説明には言葉を使わないでください：

  • 避けてください：Select **Erase job log** (the trash icon).
  • 代わりに Select **Erase job log** (**{remove}**). として生成されます：ジョブログの消去({remove}) を選択します。

ボタンにホバーテキストがない場合、アイコンを記述することができます。アクセシビリティを向上させるために、ボタンにホバーテキストを追加するUXバグイシューを作成してフォローアップしてください。

  • 避けてください：Select **{ellipsis_v}**.
  • 代わりに Select the vertical ellipsis (**{ellipsis_v}**). として生成されます：垂直省略記号({ellipsis_v}) を選択します。

動画

GitLabのYouTubeビデオチュートリアルをドキュメントに追加することは、ビデオが古くない限り、強く推奨されます。動画はドキュメントに取って代わるものではなく、ドキュメントを補完したり説明したりするものです。動画の内容が機能やその主な使用例にとって基本的なものでありながら、ドキュメントで十分にカバーされていない場合は、そうすべきです：

  • その詳細をドキュメントに追加してください。
  • イシューを作成してビデオをレビューし、ページを更新してください。

動画を製品リポジトリにアップロードしないでください。代わりにリンクするか埋め込んでください。

動画にリンクするには、YouTubeのアイコンを入れて、読者がページを読む前に動画を探せるようにします：

<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Video Title](link-to-video).

GitLabユーザーにとって有用な最新の動画であれば何でもリンクできます。

動画を埋め込む

GitLab 12.1 で導入されました。

GitLabドキュメンテーションサイトは埋め込みビデオをサポートしています。

GitLabの公式YouTubeアカウントからのみ動画を埋め込むことができます。他のソースからの動画については、代わりにリンクしてください。

ほとんどの場合、動画へのリンクを貼りましょう。埋め込み動画はページ上で多くのスペースを取り、読者の邪魔になる可能性があります。

動画を埋め込むには

  1. この手順からコードをコピーし、あなたのMarkdownファイルに貼り付けてください。上下に空白行を残してください。コードを編集しないでください（スペースを削除したり追加したりしないでください）。
  2. YouTubeで、表示したい動画のURLにアクセスします。ブラウザから通常の URL (https://www.youtube.com/watch?v=VIDEO-ID) をコピーし、動画のタイトルとリンクを<div class="video-fallback"> の下の行に置き換えます。
  3. YouTubeで「共有」を選択し、「埋め込み」を選択します。
  4. <iframe> のソース (src)URL のみ(https://www.youtube-nocookie.com/embed/VIDEO-ID) をコピーし、iframe タグ内のsrc フィールドの内容を置き換えて貼り付けます。
leave a blank line here
<div class="video-fallback">
  See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
</div>
<figure class="video-container">
  <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe>
</figure>
leave a blank line here

GitLab ドキュメントサイトでは、このように表示されます：

ビデオをご覧ください：GitLabとは？

注釈

  • figure タグはセマンティック SEO のために必要であり、video-container クラスは動画がレスポンシブに対応し、さまざまなモバイル機器で表示されるようにするために必要です。
  • <div class="video-fallback"> は、/helpGitLab Markdownプロセッサーがiframeをサポートしていないため、. /helpNETのために必要なフォールバックです。/helpドキュメントサイトでは非表示になっていますが、.NET Frameworkでは表示さ /helpれます。
  • www.youtube-nocookie.com ドメインはYouTube埋め込みプレーヤーのプライバシー拡張モードを有効にします。このモードにより、クッキーを制限しているユーザーでも埋め込みビデオを見ることができます。

アラートボックス

アラートボックスは、情報への注意を喚起するために使用します。アラートボックスは控えめに使用し、アラートボックスの直後に別のアラートボックスを表示しないようにしてください。

アラートボックスは、これらの単語の後に改行が続くと生成されます：

  • FLAG:
  • NOTE:
  • WARNING:
  • INFO: (マーケティングのみ）
  • DISCLAIMER:

使用例：

NOTE:
This is something to note.

複数の段落、リスト、ヘッダーに対してアラートボックスを表示するには、代わりにブロッククォートを使用してください。

アラートボックスはGitLabドキュメントサイト(https://docs.gitlab.com)でのみ表示されます。GitLab製品のヘルプでは、アラートボックスはプレーンテキストとして表示されます。

フラグ

このアラートタイプは、機能の可用性を説明するために使用します。FLAG アラートのフォーマット方法については、機能フラグの背後にデプロイされた機能を文書化するを参照してください。

ノート

メモは控えめに。メモが多すぎると、トピックをスキャンするのが難しくなります。

メモを追加する代わりに

  • 段落の一部として書き直しましょう。
  • 情報を段落にまとめなさい。
  • 内容を新しいトピックのタイトルの下に置いてください。

どうしても注釈が必要な場合は、この書式を使用してください：

NOTE:
This is something to note.

GitLab ドキュメントサイトでは、このように表示されます：

note
これは注意すべき点です。

警告

非推奨の機能を示したり、データ損失の可能性がある手順について警告を表示したりする場合に警告を使用します。

WARNING:
This is something to be warned about.

GitLab ドキュメントサイトでは、このように表示されます：

caution
これは警告すべきことです。

情報

マーケティングチームは、INFO アラートを使用して、営業およびマーケティング活動に関連する情報を追加します。

INFO: アラートのテキストは、常に周囲のテキストの右側にあるフローティングテキストボックスでレンダリングされます。レンダリングされた GitLab ドキュメントサイトを見るには、MR.GitLab のレビューアプリをチェックしてください。フローティングボックスを表示させたい場所に応じて、テキストを周囲のテキストの上下に移動させる必要があるかもしれません。

たとえば、あなたのページにこのようなテキストがあったとします：

This is an introductory paragraph. GitLab uses the SSH protocol to securely communicate with Git.
When you use SSH keys to authenticate to the GitLab remote server,
you don't need to supply your username and password each time.

INFO:
Here is some information. This information is an important addition to how you
work with GitLab and you might want to consider it.

And here is another paragraph. GitLab uses the SSH protocol to securely communicate with Git.
When you use SSH keys to authenticate to the GitLab remote server,
you don't need to supply your username and password each time.

And here is another paragraph. GitLab uses the SSH protocol to securely communicate with Git.
When you use SSH keys to authenticate to the GitLab remote server,
you don't need to supply your username and password each time.

GitLab ドキュメントサイトでは、このように表示されます：

これは導入の段落です。GitLabはSSHプロトコルを使ってGitとセキュアに通信します。SSHキーを使ってGitLabのリモートサーバーを認証する場合、毎回ユーザー名とパスワードを入力する必要はありません。

情報ここにいくつかの情報があります。この情報はGitLabでの作業方法にとって重要な追加情報ですので、検討してみてはいかがでしょうか。

そして、ここにも段落があります。GitLabはSSHプロトコルを使ってGitとセキュアに通信します。SSHキーを使ってGitLabのリモートサーバーを認証する場合、毎回ユーザー名とパスワードを入力する必要はありません。

そして、ここにも段落があります。GitLabはSSHプロトコルを使ってGitとセキュアに通信します。SSHキーを使ってGitLabのリモートサーバーを認証する場合、毎回ユーザー名とパスワードを入力する必要はありません。

免責事項

将来の機能を説明するためにのみ使用します。詳細については、将来の機能に関する法的免責事項をご覧ください。

ブロッククォーツ

ブロッククオート内のテキストをハイライトするには、この書式を使用します：

> This is a blockquote.

GitLab ドキュメントサイトでは、このように表示されます：

これはブロッククオートです。

テキストが複数行にまたがる場合は、分割することができます。

複数段落の場合は、各行の前に記号> を使用します：

> This is the first paragraph.
>
> This is the second paragraph.
>
> - This is a list item
> - Second item in the list

GitLab ドキュメントサイトでは、このように表示されます：

これは最初の段落です。

これが第2段落です。

  • これはリスト項目です
  • リストの2番目の項目

タブ

docsサイトでは、テキストをタブで表示するように書式設定することができます。

タブのセットを作成するには、次の例に従ってください：

::Tabs

:::TabTitle Tab One

Here's some content in tab one.

:::TabTitle Tab Two

Here's some other content in tab two.

::EndTabs

このコードは GitLab ドキュメントサイトでは次のように表示されます：

Tab One

これがタブ 1 の内容です。

Tab Two

以下はタブ2の他のコンテンツです。

タブのタイトルは、簡潔で一貫性のあるものにしましょう。また、タブのタイトルは大文字で始めます。例えば

  • Linux package (Omnibus),Helm chart (Kubernetes) (設定編集を文書化する場合は、設定編集ガイドに従ってください)
  • 15.1 and earlier,15.2 and later

タブへのリンク切れの自動テスト(イシュー 1355) が実施されるまでは、固有の URL パラメータがあっても、単一のタブに直接リンクしないでください。

タブの詳細については、パジャマを参照してください。

盗作

引用元を明記した限定的な引用でない限り、他のソースから内容をコピー＆ペーストしないでください。一般的には、関連する情報を自分の言葉で言い換えるか、他の情報源にリンクを張る方が良いでしょう。

製品と特徴

GitLab 製品ドキュメントで製品や機能を説明する際には、このセクションの情報を参照してください。

名前の改行を避ける

機能名や製品名にスペースが含まれている場合は、改行しないでください。名前が変わると、改行のあるテキストを検索したり grep したりするのが複雑になります。

製品階層バッジ

階層バッジは、機能に関する情報を提供し、トピックタイトルの横に表示されます。

階層バッジを割り当てる必要があります：

  • doc/development/* の下の Pages を除く、すべての H1 トピックタイトルに。
  • H1と同じ階層に該当しないトピック・タイトルに。

H1階層バッジは、ページ上の機能の最も低い階層に適用されるバッジであるべきです。

利用可能な製品階層バッジ

ティアバッジは、購読ティアと提供物の2つのコンポーネントをこの順序で含む必要があります。これらの構成要素は太字と括弧で囲まれます。例えば、**(ULTIMATE SAAS)** 。

サブスクリプションティア：

  • FREE - すべてのティアに適用されます。
  • PREMIUM - PremiumとUltimateに適用されます。
  • ULTIMATE - アルティメット・ティアのみに適用されます。

提供

  • SELF
  • SAAS
  • ALL - 自己管理型とSaaS型の両方に適用されます。

また、機能のステータスを示す3つ目のコンポーネントを追加することもできます：

  • EXPERIMENT
  • BETA

例えば、**(FREE ALL EXPERIMENT)**.

ティアまたはステータスは単独でも可能です。オファーは常にティアを持つべきです。

ティアバッジの追加

トピックタイトルにティアバッジを追加するには、タイトルテキストの後に関連する 2 つのコンポーネントを追加します。最初にサブスクリプションのティアを追加し、次にオファーを追加します。例

# Topic title **(FREE ALL)**

オプションで、機能ステータスをバッジの最後に追加できます：

# Topic title **(FREE ALL EXPERIMENT)**

または、ステータスを単独で追加します：

# Topic title **(EXPERIMENT)**
インライン・ティアバッジ

API 属性を除き、階層バッジを他のテキストとインラインで追加しないでください。機能の唯一の真実の情報源は、その機能が説明されているトピックであるべきです。

階層バッジが不要なページ

明らかなティアバッジが適用されないため、ティアバッジがないページもあります。例えば

  • チュートリアル
  • 異なる階層の機能を比較するページ。
  • /development フォルダ内のページ。これらのページには自動的にContribute バッジが割り当てられます。
管理者ドキュメントの階層バッジ

インスタンス管理者のみを対象としたトピックには、<TIER> SELF のバッジを付けるべきです。 インスタンス管理者のドキュメントには、以下のようなセクションが含まれることがよくあります：

  • gitlab.rb またはgitlab.yml ファイルの変更。
  • rails コンソールへのアクセスや Rake タスクの実行。
  • 管理エリアでの操作。

これらのPagesは、タスクがインスタンス管理者によってのみ達成可能である場合についても言及する必要があります。

特定のセクション

特定のセクションには、特定のスタイルを適用する必要があります。特定のセクションのスタイルについては、このセクションで説明します。

ヘルプとフィードバックのセクション

このセクション(GitLab 11.4で導入)は各ドキュメントの最後に表示され、フロントマターにキーを追加することで省略することができます：

---
feedback: false
---

デフォルトはこのままです。ドキュメントから省略したい場合は、テクニカルライターに確認してください。

フィードバックセクションのクリックイベントはGoogle Tag Managerでトラッキングされます。コンバージョンはGoogle Analyticsの行動 > イベント > トップイベント > docsで確認できます。

GitLabリスタート

GitLabの再起動や再設定が必要な場合は、doc/administration/restart_gitlab.md 。必要に応じて’reconfigure’を’restart’に置き換えてください：

Save the file and [reconfigure GitLab](../../../administration/restart_gitlab.md)
for the changes to take effect.

ドキュメントがdoc/ ディレクトリの外部にある場合は、相対リンクの代わりにフルパスを使います：https://docs.gitlab.com/ee/administration/restart_gitlab.html.

異なるインストール方法を文書化する方法

GitLabは5つの公式インストール方法をサポートしています。文章やタイトルの一部として単語を参照する場合は、次のフレーズを使います：

  • Linuxパッケージ
  • Helmチャート
  • GitLab オペレーター
  • Docker
  • セルフコンパイル

タブを使用する場合は、説明用の括弧を追加しても問題ありません：

  • Linuxパッケージ(Omnibus)
  • Helmチャート (Kubernetes)
  • GitLab オペレーター (Kubernetes)
  • Docker
  • セルフコンパイル（ソース）

タブを使用して、自己管理された設定手順を記述します。

設定手順では、ユーザーが設定ファイルを編集したり、GitLabを再設定したり、GitLabを再起動したりする必要があります。この場合

  • タブを使用して、様々なインストール方法を区別します。
  • インストール方法の名前は、前のリストで説明したとおりに使用してください。
  • 以下の順序で使用してください。
  • コード・ブロックのインデントは、そのブロックが属するリスト・アイテムに合わせてください。
  • 各コード・ブロックには、適切な構文強調表示 (ruby,shell, またはyaml) を使用します。
  • YAMLファイルでは、常に親設定を含めます。
  • GitLabを再設定したり再起動したりする最後のステップは、毎回同じなのでそのまま使えます。

設定の編集を説明するときには、次のスニペットを使ってお好みに編集してください：

::Tabs

:::TabTitle Linux package (Omnibus)

1. Edit `/etc/gitlab/gitlab.rb`:

   ```ruby
   external_url "https://gitlab.example.com"
   ```

1. Save the file and reconfigure GitLab:

   ```shell
   sudo gitlab-ctl reconfigure
   ```

:::TabTitle Helm chart (Kubernetes)

1. Export the Helm values:

   ```shell
   helm get values gitlab > gitlab_values.yaml
   ```

1. Edit `gitlab_values.yaml`:

   ```yaml
   global:
     hosts:
       gitlab:
         name: gitlab.example.com
   ```

1. Save the file and apply the new values:

   ```shell
   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   ```

:::TabTitle Docker

1. Edit `docker-compose.yml`:

   ```yaml
   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           external_url "https://gitlab.example.com"
   ```

1. Save the file and restart GitLab:

   ```shell
   docker compose up -d
   ```

:::TabTitle Self-compiled (source)

1. Edit `/home/git/gitlab/config/gitlab.yml`:

   ```yaml
   production: &base
     gitlab:
       host: "gitlab.example.com"
   ```

1. Save the file and restart GitLab:

   ```shell
   # For systems running systemd
   sudo systemctl restart gitlab.target

   # For systems running SysV init
   sudo service gitlab restart
   ```

::EndTabs

のようにレンダリングされます：

Linux package (Omnibus)

  1. /etc/gitlab/gitlab.rb を編集します：

    external_url "https://gitlab.example.com"

  2. ファイルを保存して GitLab を再設定してください：

    sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)

  1. Helm の値をエクスポートします：

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml を編集します：

    global:
  hosts:
    gitlab:
      name: gitlab.example.com

  3. ファイルを保存して、新しい値を適用します：

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

  1. docker-compose.yml を編集します：

    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url "https://gitlab.example.com"

  2. ファイルを保存して GitLab を再起動します：

    docker compose up -d
Self-compiled (source)

  1. /home/git/gitlab/config/gitlab.yml を編集します：

    production: &base
  gitlab:
    host: "gitlab.example.com"

  2. ファイルを保存して GitLab を再起動します：

    # For systems running systemd
sudo systemctl restart gitlab.target
   
# For systems running SysV init
sudo service gitlab restart