ドキュメントのフォルダ構造
ドキュメントは、トップレベルのオーディエンスフォルダuser、administration、development （貢献する）フォルダによって分けられています。
それ以上は、主に GitLab のユーザーインターフェイスや API の構造に従っています。
私たちの目標は、docs.gitlab.com/user/project/merge_requests/ のような意味のある URL を持つ明確な階層構造を持つことです。このパターンでは、プロジェクトの機能に関するユーザー関連のドキュメント、特にマージリクエストに関するドキュメントに移動していることがすぐにわかります。私たちのサイトのパスはリポジトリと一致しているので、明確な構造はドキュメントの更新も容易にします。
特定の製品エリアのファイルを関連フォルダに入れます：
| ディレクトリ | 目次 |
|---|---|
doc/user/ | ユーザー向けのドキュメントです。GitLabユーザーインターフェースでできることは、/admin インターフェースの使い方も含めて、すべてここにあります。 |
doc/administration/ | GitLabがインストールされているサーバーにユーザーがアクセスする必要があるドキュメント。GitLabユーザーインターフェースの管理者設定はdoc/administration/。 |
doc/api/ | APIのドキュメント。 |
doc/development/ | GitLabの開発に関連するドキュメントで、コードやドキュメントに貢献するもの。関連するプロセスやスタイルガイドはこちらへ。 |
doc/legal/ | GitLabに貢献することに関する法的文書。 |
doc/install/ | GitLabのインストール方法。 |
doc/update/ | GitLabをアップデートする手順。 |
doc/tutorials/ | GitLabの使い方のチュートリアル。 |
以下はレガシーフォルダや非推奨のフォルダです。これらのフォルダに新しいコンテンツを追加しないでください：
/gitlab-basics//topics//university/
ディレクトリとファイルの操作
ディレクトリやファイルを扱う場合
- 新しいディレクトリを作成するときは、必ず
index.mdファイルから始めます。他のファイル名を使用したり、README.mdファイルを作成しないでください。 - ファイル名、ディレクトリ名、ブランチ名、およびパスを生成するものには、特殊文字やスペース、大文字を使用しないでください。
- ファイル名やディレクトリ名を作成または変更する際、ファイル名に複数の単語が含まれる場合は、スペースやダッシュの代わりにアンダースコア (
_) を使用してください。例えば、適切な命名はimport_project/import_from_github.mdとなります。これは画像ファイルとMarkdownファイルの両方に適用されます。 - 製品リポジトリに動画ファイルをアップロードしないでください。代わりに動画をリンクするか埋め込んでください。
-
doc/user/：-
doc/user/project/には、プロジェクトに関連するすべてのドキュメントが含まれているはずです。 -
doc/user/group/グループ関連のすべてのドキュメントが含まれている必要があります。 -
doc/user/profile/には、プロファイル関連のドキュメントがすべて含まれている必要があります。/profileの下にナビゲートされるすべてのページには、account.md、applications.md、emails.mdのように、それぞれのドキュメントがあるべきです。
-
-
doc/administration/ディレクトリ: UI とバックエンドサーバの両方で行われる管理タスクを含む、管理者向けのすべての管理者関連ドキュメント。
ドキュメントやコンテンツの追加をどこに置くか迷ったとしても、作成者や貢献者を止めるべきではありません。あなたの最善の判断で、MRのレビュアーにあなたの判断を確認してもらいましょう。また、プロセスのどのステージでも、テクニカルライターに尋ねることができます。テクニカルライティングチームは、ドキュメントの変更に関係なく、すべてのドキュメントをレビューし、より良い場所があればコンテンツを移動させることができます。
重複を避ける
同じ情報を複数の場所に記載しないでください。代わりに真実の単一の情報源にリンクしてください。
例えば、プライマリリポジトリ以外のリポジトリにコードがあり、同じリポジトリにドキュメントがある場合、ドキュメントはそのリポジトリに置いておくことができます。
そうすれば、次のどちらかを行うことができます：
- https://docs.gitlab.com に公開します。
- グローバルナビゲーションにエントリを追加して、https://docs.gitlab.com からリンクします。例をご覧ください。
ドキュメント間の参照
- トピックを紹介し、次のレベルのサブパスのインデックスページを含む子ページを紹介し、リンクする
index.mdページを各フォルダに与えます。 - 発見しやすくするため、新しいドキュメントや名前を変更したドキュメントには、上位のインデックスページや他の関連ページからリンクするようにしてください。
- 他のGitLab製品や機能を参照するときは、少なくとも最初に言及するときは、それぞれのドキュメントにリンクしてください。
- サードパーティの製品やテクノロジーに言及する場合は、それらの外部サイト、ドキュメント、リソースにリンクしてください。