ソリューションアーキテクト GitLab Docs セクション

目的

包括的な目的は、GitLab で構築されたソリューションが GitLab のドキュメンテーション内に居場所を持ち、そのようなソリューションの発見と支持を支援し、場合によっては GitLab によって認識され、積極的に保守されているとして扱われるようにすることです。

公式 GitLab ドキュメンテーションは、ソフトウェア製品ドキュメンテーションにおける業界標準の卓越性に関して管理されています。この点で公式ドキュメンテーションは:

• GitLab 自体の公式機能のみに焦点を当てるようにスコープされています。
• ページに対して特定の構造に従います。
• 方法のチュートリアルコンテンツは、同じ機能をドキュメント化する関数となる傾向があるため、通常小さな機能セットのシナリオに焦点を当て続けます。

過去には、ソリューション指向のアイテムが GitLab のブログでも公開されていました。ソリューションドキュメンテーション領域はブログとは以下のように異なります:

• ブログ記事は簡潔さのために編集されますが、ソリューションは長さに関係なく、特定の機能と関数が動作することを示すために編集されます。
• ブログ記事は、読者によって時間とともに古くなり正確性が低下することが知られていますが、ソリューションでドキュメント化されたアイテムは動作する状態で維持されることを意図しています。
• ブログ記事は古くなるにつれて検索で見つけにくくなりますが、ソリューションは比較的見つけやすい状態を保つべきです。

ソリューションドキュメンテーションセクションの作成により、これらのいくつかの方法で製品ドキュメンテーションよりも一般的に広いやり方で最良に作成されるソリューションのドキュメンテーションが可能になります:

• GitLab と統合するパートナー製品の機能に焦点を当てることができる
• GitLab の多くの部分の機能を、また非 GitLab テクノロジーと組み合わせて活用するソリューションに焦点を当てることができる

ソリューション領域は SA チームの完全なスチュワードシップ下にあり、Tech Writing によって積極的にレビューされません。ソリューションドキュメンテーションセクションは、GitLab のテックライティングが設定する卓越性のバーを満たすよう努めます。すべての貢献者はGitLab 内部テックライティングコースを受講することが推奨されます。

コンテンツのスコープ

ソリューション領域はソリューション指向のアセットを考慮するためにより柔軟ですが、新鮮で正確である必要もあります。コンテンツの新鮮さレビュープロセスは以下に特定されています。加えて、このコンテンツのスコープは、編集の負担増加につながりがちなより不安定な情報がドキュメンテーションとして保存されないことを保証するのに役立ちます。

ドキュメンテーションマージプロセス

Solution Docs の MR が、ドキュメンテーションの変更が通常のテック編集プロセスと CI ジョブを通らずに、代わりに Solutions Docs の最適化されたワークフローを通るよう、適切な MR テンプレートを使用することが重要です。

1. https://gitlab.com/gitlab-org/gitlab で変更を準備します
2. 重要: マージリクエストを準備するときは、「Documentation SA Solutions Docs」と呼ばれる MR テンプレートを使用してください
   1. これは “docs::improvement” ラベルを残し、“Solutions” ラベルを追加します (これは実行される CI ジョブにも影響します)
   2. これは適切なレビュアーを追加します (MR テンプレートはここで確認できます: https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation%20SA%20Solutions%20Docs.md)

ページのソースコードを見る - ページの編集 - please contribute.