GitLab ドキュメンテーションガイドライン

GitLabのドキュメントは、GitLabの設定、使い方、トラブルシューティングの方法に関する情報を、(SSOT)、 単一の真実のソースとして提供することを目的としています。 ドキュメントには、すべてのGitLab機能のユースケースと使い方の説明が、製品分野やテーマごとにまとめられています。 これには、複数のGitLab機能にまたがるトピックやワークフロー、他のアプリケーションとのGitLabの使い方も含まれます。

このページに加え、以下のリソースは、あなたが文書を作成し貢献するのに役立ちます：

ソースファイルとレンダリングされたウェブの場所

GitLab、GitLab Runner、Omnibus GitLab、Chartsのドキュメントは、https://docs.gitlab.com。 GitLabのドキュメントは、/help GitLabインスタンスのドメイン上の /helpアプリケーション内部でも公開されています/help 。 では /help、現在のエディションとバージョンのヘルプのみが含まれています。 他のバージョンのヘルプは、https://docs.gitlab.com/archives/。

ドキュメントのソースは、各 GitLab アプリケーションのコードベース内の以下のリポジトリに存在します：

プロジェクト パス
GitLab /doc
GitLab Runner /docs
オムニバス GitLab /doc
チャート /doc

ドキュメンテーションイシューとマージリクエストはそれぞれのリポジトリの一部であり、すべてDocumentationというラベルがついています。

ブランチのネーミング

GitLabのメインプロジェクトのCIパイプラインは、貢献の種類にマッチしたジョブだけを自動的に実行するように設定されています。 貢献がドキュメントの変更だけを含む場合、ドキュメント関連のジョブだけが実行され、パイプラインはコードの貢献よりもずっと速く完了します。

ドキュメントのみの変更をRunner、Omnibus、Chartに提出する場合、高速パイプラインは自動的に決定されません。 代わりに、以下のガイドを使ってドキュメントのみのマージリクエスト用のブランチを作成してください：

Branch name 有効な例
まずはdocs/ docs/update-api-issues
まずはdocs- docs-update-api-issues
終了-docs 123-update-api-issues-docs

ドキュメントへの貢献者

GitLabドキュメントへの貢献者は、GitLabコミュニティ全体から歓迎されています。

GitLabのドキュメントが最新であることを保証するために、すべての機能の変更、つまり機能の外観、使い方、管理に影響を与える開発者には特別なプロセスと責任があります。

例えば、GitLabやサードパーティツールとGitLabですでに可能なユースケースを達成する方法について新しいドキュメントを追加するなどです。

マークダウンとスタイル

GitLab docsはMarkdownレンダリングエンジンとしてGitLab Kramdownを使用しています。 Kramdownの完全なリファレンスはGitLab Markdown Guideをご覧ください。

ドキュメント・スタイル・ガイドを遵守してください。 スタイル標準がない場合は、マージリクエストで提案してください。

フォルダ構造とファイル

ドキュメンテーション・スタイル・ガイド」の「構造」のセクションを参照してください。

メタデータ

追加のディレクティブや有用な情報を提供するために、それぞれの製品のドキュメントページの先頭にYAMLフォーマットのメタデータを追加します (YAMLフロントマター)。 すべての値は文字列として扱われ、docsのWebサイトでのみ使用されます。

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

各ページには、そのページが属するステージやグループに関連するメタデータと、以下に説明するような情報ブロックがあるのが理想的です：

  • stageページのコンテンツの大部分が属するステージ。
  • groupページのコンテンツの大部分が属するグループ。

  • 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

例えば、以下のメタデータは、主に監査イベント機能に関連する製品ドキュメント・ページの冒頭にあります： 

---
stage: Monitor
group: APM
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
---

ページタイプのメタデータ

もともとこのエピックで説明したように、各ページはtype メタデータを持つべきです。メタデータは以下のうちの1つ以上です：

  • index: 索引/概要ページ。 他のページへのリストとして機能します。 必ずしもそのページがindex.mdという名前でなければならないというわけではありません。例ページ。
  • concepts製品を使用する前に知っておくべきこと。 例えば、アイデアを抽象化する、意味や利益を説明する、タスクの理解をサポートする、など。 なぜXが重要なのか」など、背景情報を得るために読まれます。例ページ。
  • howto具体的な使用例の説明。例ページ。
  • tutorial例ページ。
  • reference具体的な設定や、あまり説明のない事実など、詳細な情報を得るために読まれるPages。例ページ。

リダイレクション・メタデータ

ページが別の場所に移動された場合、以下のメタデータを追加する必要があります：

  • redirect_to: 移動したページの訪問者をリダイレクトする場所の相対パスとファイル名 (.md 拡張子付き)。詳しくはこちら。
  • disqus_identifierDisqusコメントシステムの識別子。 新しいURLに移動されたページのコメントを保持するために使用されます。 詳細はこちら。

コメント・メタデータ

docs のウェブサイトでは、デフォルトでコメント (Disqus が提供) が有効になっています。 (インデックスページなどで) コメントを無効にしたい場合は、falseに設定してください： 

---
comments: false
---

追加ページのメタデータ

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

  • authorチュートリアルを表示するにはauthor_gitlab が必要です。
  • author_gitlab: GitLab.comでの作成者のユーザー名。表示するにはauthor 。
  • dateページが作成された日付（通常はチュートリアル用）。
  • article_typetutorial 、 。user guide
  • levelbeginner, , のいずれかです。advancedintermediate
  • last_updatedページが最後に更新されたISO形式の日付。 例：2020-02-14.
  • reading_timeページのおおよその読書時間の表示を追加したい reading_time場合は、trueにreading_time設定 reading_timeします。 これは、簡単なアルゴリズムを使って、単語数に基づいて読書時間を計算します。

ドキュメントの場所の変更

ドキュメントの場所を変更するには、ユーザーがGitLabインスタンスドメイン/help のコンテンツにアクセスする場合でも、https://docs.gitlab.comのコンテンツにアクセスする場合でも、新しいdocページにシームレスにアクセスできるようにするための特別な手順が必要です。（移動が必要かどうかなど）プロセス中に質問がある場合は必ずテクニカルライターを割り当て、マージする前にテクニカルライターがこの変更をレビューするようにしてください。

ドキュメントの場所を変更する必要がある場合は、古いドキュメントを削除せずに、その内容をすべて以下のように置き換えてください： 

---
redirect_to: '../path/to/file/index.md'
---

This document was moved to [another location](../path/to/file/index.md).

../path/to/file/index.md は通常、古いドキュメントへの相対パスです。

redirect_to 変数は、完全 URL と相対 URL の両方をサポートしています。例えば、https://docs.gitlab.com/ee/path/to/file.html,../path/to/file.html,path/to/file.mdのようになります。これは、リダイレクトがhttps://docs.gitlab.com で機能することを保証し、*.md のパスは*.htmlにコンパイルされます。フロントマターの下の新しい行は、ドキュメントの場所が変更されたことをユーザーに知らせ、リポジトリからそのファイルをブラウズする人にとって便利です。

例えば、doc/workflow/lfs/index.md をdoc/administration/lfs.mdに移動する場合、手順は次のようになります：

  1. doc/workflow/lfs/index.md にコピーします。doc/administration/lfs.md

  2. doc/workflow/lfs/index.md の内部を置き換えてください： 

    ---
redirect_to: '../../administration/lfs.md'
---

This document was moved to [another location](../../administration/lfs.md).

  3. 古い場所を検索し、新しい場所に置き換えます。すばやく検索するには、ファイルを変更したリポジトリのgit grep を使用します： 

    git grep -n "workflow/lfs/lfs_administration"
git grep -n "lfs/lfs_administration"
注意: 移動するドキュメントにDisqusのコメントがある場合、以下に示す特別な手順を踏む必要があります。

注意すべきこと

  • インラインドキュメントも使っているので、ドキュメントそのものを除けば、ドキュメントはGitLabのビュー (app/) でも参照されるかもしれません。/helpにアクセスしたときにレンダリングされますし、テストスイート (spec/) でも参照されることがあります。これらのパスでドキュメントへの参照を探し、更新する必要があります。
  • 上記のgit grep コマンドは、実行したディレクトリ内のworkflow/lfs/lfs_administration とlfs/lfs_administrationを再帰的に検索し、そのファイルと、そのファイルについて言及されている行を表示します。 なぜ2つのgrepを使うのかと聞かれるかもしれません。ドキュメントへのリンクには相対パスを使用するため、より深いパスを検索すると便利な場合があります。
  • ドキュメントがGitLabのビルトインヘルプページにリンクされている場合は、*.md 拡張子は使われません。そのため、git grepでは省略しています。
  • MRの説明テンプレート「Change documentation location」のチェックリストを使用してください。

Disqusコメント付きページのリダイレクト

移転先のドキュメントページにすでにDisqusコメントがある場合、Disqusスレッドを維持する必要があります。

Disqusはページごとに識別子を使用し、https://docs.gitlab.comの場合、ページ識別子はページURLとなるように設定されています。 そのため、ドキュメントの場所を変更した場合、同じDisqus識別子として古いURLを保持する必要があります。

そのためには、古いURLを値として、変数disqus_identifierをフロントマターに追加します。 例えば、https://docs.gitlab.com/my-old-location/README.html で利用可能なドキュメントを新しい場所、https://docs.gitlab.com/my-new-location/index.htmlに移動したとします。

新しい文書のフロント・マターに以下を追加します： 

---
disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html'
---

注：index.html またはREADME.htmlの場合でも、disqus_identifier のURLにファイル名を含める必要があります。

GitLab ドキュメントのマージリクエスト

作業を始める前に、上記の入門編「docsに貢献する」とドキュメントのワークフローを読んでください。

  • 現在のマージリクエスト記述テンプレートを使用します。
  • MRDocumentation にラベルを付けます（GitLab チームメンバーなど、developer にアクセスできる人だけができます）。
  • 以下の注釈に従って、正しいマイルストーンを割り当ててください（GitLabチームメンバーなど、developer にアクセスできる人のみが行うことができます）。

文書がマージされるのは、それが既存の内容を改善するものであり、テンプレートとスタイル標準に従う誠実な努力を示すものであり、正確であると考えられる場合です。

ドクターをさらに良くするためのさらなるニーズは、フォローアップのMRやイシューで即座に対応すべきです。

注意: ドキュメントを追加したいリリースのバージョンが、すでに凍結またはリリースされている場合、ラベル~"Pick into X.Y" を使って、正しいリリースにマージしてください。 リリースマネージャの作業が増えるので、できるだけ過去のリリースを選ぶのは避けてください。

GitLab/help

すべてのGitLabインスタンスにはドキュメントが含まれており、/help(https://gitlab.example.com/help) にあります。例えば、https://gitlab.com/help。

https://docs.gitlab.com 上でオンラインで利用可能なドキュメントは、GitLab、Omnibus、Runner のmaster ブランチから 4 時間ごとにデプロイされます。したがって、マージリクエストがマージされると、その日のうちにオンラインで利用可能になります（/help）。ただし、MR に割り当てられたマイルストーン内で出荷されます。

例えば、あなたのマージリクエストのマイルストーンが2018-09-22にリリースされる11.3に設定されているとします。2018-09-15にマージされれば、2018-09-15にオンラインで利用できるようになりますが、機能凍結日が過ぎているため、MRに~"Pick into 11.3" ラベルがなければ、マイルストーンを11.4に変更しなければならず、2018-10-22にGitLab 11.4のみですべてのGitLabパッケージと一緒に出荷されます。つまり、GitLab 11.4以降は/help の下でのみ利用できるようになりますが、https://docs.gitlab.com/ ではマージされたその日に利用できるようになります。

リンク/help

新しい機能をビルドするとき、アプリケーションである GitLab からドキュメントをリンクする必要があるかもしれません。 これは通常、help_page_path ヘルパーメソッドの助けを借りてapp/views/ ディレクトリ内部のファイルで行います。

最も単純な形では、/help ページへのリンクを生成する HAML コードは次のようになります： 

= link_to 'Help page', help_page_path('user/permissions')

help_page_path には、リンクしたい文書へのパスを以下の規則で記述します：

  • GitLab リポジトリのdoc/ ディレクトリからの相対パスです。
  • .md の拡張子は省略可能です。
  • スラッシュ (/) で終わってはいけません。

以下は、文脈に応じて使用すべき特別なケースです。 以下の1つ以上を組み合わせることができます：

  1. アンカーリンクへのリンク。 help_page_pathメソッドの一部としてanchor を使用します： 

    = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')

  2. リンクは新しいタブで開きます。これはデフォルトの動作です： 

    = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'

  3. サークルアイコンへのリンク。通常、チェックボックスの近くなど、長い説明を使用できない設定で使用します。 基本的にどのようなフォントの素晴らしいアイコンでも使用できますが、question-circle： 

    = link_to icon('question-circle'), help_page_path('user/permissions')

  4. ボタンリンクを使用することで、テキストが他のページレイアウトの文脈から外れてしまうような場合に便利です： 

    = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'

  5. テキストのインラインでリンクを使用します。 

    Description to #{link_to 'Help page', help_page_path('user/permissions')}.

  6. 文末にピリオドを追加します。ピリオドをリンクの一部にしたくない場合に便利です： 

    = succeed '.' do
  Learn more in the
  = link_to 'Help page', help_page_path('user/permissions')

GitLab/help テスト

いくつかのRSpecテストは、GitLabドキュメントが正しくレンダリングされ、正しく動作することを確認するために実行されます。 特に、メインのdocsランディングページは、/helpから正しく動作します。例えば、GitLab.com の/help.

ドキュメント・サイト・アーキテクチャ

https://docs.gitlab.com 、どのようにサイトを構築しデプロイしているのか、また使用されているすべてのアセットとライブラリを確認するには、Docsサイトアーキテクチャページをご覧ください。

左側ナビゲーションメニューの構築と更新方法については、グローバルナビゲーションdocをご覧ください。

変更をライブでプレビュー

注意:ドキュメントへの変更をローカルでプレビューするには、この開発者ガイドまたはGDKの説明に従ってください。

ライブプレビューは現在、以下のプロジェクトで有効になっています：

マージリクエストにdocsの変更がある場合、手動review-docs-deploy ジョブを使用して、マージリクエストのdocsレビューアプリをデプロイすることができます。 実行するには少なくともメンテナー権限が必要です。

Manual trigger a docs build

注意:これらのリポジトリにはブランチをプッシュする必要があります。

review-docs-deploy* のジョブは以下の通りです：

  1. gitlab-docsプロジェクト内に、docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IIDというスキームにちなんだ新しいブランチを作成します。DOCS_GITLAB_REPO_SUFFIX は各プロダクトのサフィックスで、例えば、ee は EE、omnibus は Omnibus GitLab など、CI_MERGE_REQUEST_IID はそれぞれのマージリクエストの ID です。
  2. クロスプロジェクトパイプラインをトリガーし、変更を加えてドキュメントサイトを構築します。

レビューアプリの URL が 404 を返した場合、サイトがまだデプロイされていないか、リモートパイプラインで何か問題が発生したことを意味します。 数分待てばオンラインに表示されるはずです。そうでなければ、マージリクエストのジョブ出力のリンクからリモートパイプラインのステータスを確認できます。パイプラインが失敗したり、スタックした場合は、#docs のチャットチャンネルに連絡してください。

ヒント:GitLabプロジェクトへのマージ権限がない人（コントリビューターからのフォークを考えてください）は、手動ジョブを実行することができません。 その場合は、権限のあるGitLabチームの誰かに依頼することができます。
注意:自分が作業していたマージリクエストのブランチは必ず削除してください。 そうしないと、リモートのドキュメントブランチも削除されず、レビューアプリがホスティングされているサーバーのディスク容量が足りなくなります。

レビューアプリのトラブルシューティング

レビューアプリのURLが404を返した場合は、以下の手順に従ってデバッグしてください：

  1. マージリクエストウィジェットのURLをたどりましたか？もしそうなら、リンクがジョブ出力のものと同じかどうか確認してください。
  2. ジョブの出力から URL をたどりましたか？もしそうなら、サイトがまだデプロイされていないか、リモートパイプラインに何か問題があったということです。 数分待てばオンラインになるはずです。そうでなければ、ジョブの出力にあるリンクからリモートパイプラインのステータスを確認できます。パイプラインが失敗したり、スタックした場合は、#docs チャットチャンネルに連絡してください。

技術的側面

詳細についてお知りになりたい方は、こちらをご覧ください：

  1. マージリクエストでreview-docs-deploy ジョブを手動で実行します。
  2. このジョブは、scripts/trigger-build-docsスクリプトをdeploy フラグ付きで実行します：
    1. ブランチ名を入力し、以下を適用します：
      • docs-preview- のプレフィックスが追加されます。
      • プロダクトスラッグは、レビューアプリがどのプロジェクトから生まれたかを知るために使用されます。
      • gitlab-docs ブランチ名でマージリクエストの元がわかるように、マージリクエストの番号が追加されます。
    2. リモートブランチが存在しない場合は、そのブランチが作成されます (つまり、手動ジョブは何度でも再実行でき、このステップはスキップされます)。
    3. docsプロジェクトで新しいクロスプロジェクトパイプラインが起動します。
    4. プレビューURLはジョブ出力とマージリクエストウィジェットの両方に表示されます。 リモートパイプラインへのリンクも取得できます。
  3. docsプロジェクトでは、パイプラインが作成され、ビルド時間を短縮するためにテストジョブをスキップします。
  4. docsサイトが構築されると、HTMLファイルはアーティファクトとしてアップロードされます。
  5. docsプロジェクトにのみ関連付けられた特定のRunnerは、アーティファクトをダウンロードするレビューアプリジョブを実行し、rsync 、NGINXがそれらを提供する場所にファイルを転送するために使用します。

特に以下のGitLabの機能が使用されています：

テスト

私たちはドキュメントをコードとして扱っているため、ドキュメントの標準と品質を維持するためにCIパイプラインでテストを使用しています。 現在のテストは、新しいドキュメントや変更されたドキュメントのマージリクエストが提出されたときにCIジョブで実行されます：

  • docs lintドキュメント自体の内容に関するいくつかのテストを実行します：
    • lint-doc.sh スクリプトは以下のチェックとリンターを実行します：
      • すべての cURL の例では、長いフラグが使用されています (例:-Hではなく--header)。
      • CHANGELOG.md には重複バージョンは含まれていません。
      • doc/ 、実行可能なファイルはありません。
      • 新たなREADME.md 。
      • マークダウンリント
      • ベイル
    • ナノックのテスト
      • internal_linksはすべての内部リンク (例:[link](../index.md)) が有効かどうかをチェックします。
      • internal_anchorsは、すべての内部アンカー (例:[link](../index.md#internal_anchor)) が有効であることをチェックします。

テストの実行

変更をローカルでプレビューするだけでなく、すべてのlintチェックとNanocテストをローカルで実行することもできます。

ナノックテスト

Nanocテストをローカルで実行する場合：

  1. gitlab-docs ディレクトリに移動します。

  2. 以下を実行する: 

    # Check for broken internal links
bundle exec nanoc check internal_links

# Check for broken external links (might take a lot of time to complete).
# This test is set to be allowed to fail and is run only in the gitlab-docs project CI
bundle exec nanoc check internal_anchors

糸くずチェック

Lintチェックはlint-doc.shスクリプトによって実行され、以下のように実行できます：

  1. gitlab ディレクトリに移動します。

  2. 以下を実行する: 

    MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh

MD_DOC_PATH は、lintチェックを実行したいファイルまたはディレクトリを指します。 完全に省略すると、デフォルトでdoc/ ディレクトリになります。 出力は以下のようになるはずです： 

=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
✔ Linting passed

このためには、あなたのマシンに必要なlintツールがインストールされているか、Dockerがインストールされている必要があります。

地元のリンター

ドキュメント・スタイル・ガイドラインを遵守し、ドキュメントに追加する内容を改善するために、ドキュメント・リンターをインストールし、コード・エディターとインテグレーションしてください。

GitLabでは、主に以下のものを使っています：

マークダウンリント

markdownlintはMarkdown構文が特定のルールに従っているかチェックし、docs-lint テストで使用されます。

GitLabドキュメンテーションのためにMarkdown構文を選択する際にどのような選択をしなければならないかについて、私たちのドキュメンテーションスタイルガイドとMarkdownガイドが詳しく説明しています。 このツールは、これらのガイドラインからの逸脱をキャッチするのに役立ちます。

markdownlintの設定は以下のプロジェクトにあります：

この設定はビルドパイプラインでも使用されます。

markdownlintが使えます：

ヴェール

Valeは、英語の文法・スタイル・語法リンターです。 Valeの設定は、プロジェクトのルートディレクトリにある.vale.ini ファイルに保存されます。

Vale は、いくつかのタイプのチェックを拡張したカスタムテストの作成をサポートしています。これらのテストは、プロジェクトの documentation ディレクトリ内の.linting/vale/styles/gitlab ディレクトリに保存されます。

ベイルのコンフィギュレーションは以下のプロジェクトにあります：

この設定はビルドパイプラインでも使用されます。

ヴェイルは使えます：

リンターの取り付け

最低限、markdownlintと Valeをインストールして、ビルドパイプラインで実行されるチェックと一致させてください：

  1. markdownlint-cliをインストールしてください：

    • npm: 

       npm install -g markdownlint-cli

    • yarn: 

       yarn global add markdownlint-cli

      ドキュメントのlintingDockerイメージで現在使用されているmarkdownlint-cli のバージョンをインストールすることをお勧めします。

  2. valeをインストールします。例えば、brew for MacOS を使ってインストールするには、次のように実行します： 

    brew install vale

    ドキュメントのlintingDockerイメージで現在使用されているバージョンのValeをインストールすることをお勧めします。

markdownlintとValeをコマンドラインで使うだけでなく、これらのツールをコードエディターにインテグレーションすることもできます。

エディタの設定

エディタ内でmarkdownlintを設定するには、必要に応じて以下のいずれかをインストールしてください：

エディタ内でValeを設定するには、適切な以下のいずれかをインストールしてください：

ベイル・サーバーは使っていません。

ベールテストの無効化

ドキュメントの任意の部分について、特定のVale lintingルールまたはすべてのVale lintingルールを無効にすることができます：

  • 特定のルールを無効にするには、<!-- vale gitlab.rulename = NO --> タグをテキストの前に追加し、<!-- vale gitlab.rulename = YES --> タグをテキストの後に追加します。rulename はGitLab stylesディレクトリにあるテストのファイル名に置き換えてください。
  • すべてのヴェイル・リンティング・ルールを無効にするには、テキストの前に<!-- vale off --> タグを、テキストの後に<!-- vale on --> タグを追加します。

可能な限り、問題のあるルールと行だけを除外してください。 リスト項目などの場合、イシュー#175が解決するまで、リスト全体のリンティングを無効にする必要があるかもしれません。

詳しくはヴァーレのドキュメントをご覧ください。

デンジャーボット

GitLabはコードレビューのいくつかの要素にDangerを使用しています。マージリクエストにおけるdocsの変更のために、/docのファイルが変更されるたびに、Danger Botはドキュメントプロセスに関するさらなる指示をコメントに残します。これはGitLabリポジトリの/danger/documentation/のDangerfile で設定します。