ドキュメントとナレッジ記事の違い
このセクションは、ドキュメントとナレッジ記事についてより詳しい情報を提供するために用意されています。
GitLab におけるナレッジ記事と製品ドキュメント
ナレッジ記事を作成すべきか、ドキュメントを更新すべきかの判断は時に難しいことがあります！ 私たちの目標は、ドキュメントとナレッジ記事の違い、それぞれがどう異なり、どう連携できるかを理解していただくことです。最善の判断をしてください！ こう考えてみてください……迷ったらナレッジ記事を作成しましょう。ナレッジを蓄積する。後からいつでも調整できます。
ナレッジ記事 は問題解決やトラブルシューティング向けです！ これは顧客が抱える特定の Issue 向けです。ナレッジ記事は 受動的 で、顧客の Issue に即座のソリューションを提供するためにサポートチケットから作成されます。 対象は、Issue を抱える顧客、チケットを解決するサポートエンジニア、特定のエラーメッセージや問題の修正を探している人です。
ドキュメント は学習と実装のためのものです。ドキュメントはユーザーが GitLab の機能を最初から学ぶのを助けます。ドキュメントは 能動的 で、物事がどう動作すべきかを説明する戦略的なコンテンツです。対象はより、GitLab を学ぶ新規ユーザー、管理者、機能や機能性を開発する人向けです。ガイダンスとして使ってください。
ナレッジ記事を作成すべきとき
ほとんどの環境で動作するが、特定の構成では失敗するもの
サードパーティの統合やツールが関係するもの
バージョン依存
Issue にユニークさがあるもの
トラブルシューティング（手順と診断）を支援できるもの
一時的な修正があり、顧客に伝える必要があるもの
顧客が試せる代替手段があるもの
エラー状態からの復旧手順
簡易な修正（動作実績のある回避策である可能性がある）
同じ症状に対して複数の原因があるもの
移行またはアップグレード固有の情報
既知の Issue
GitLab ナレッジ記事の例:
「GitLab 15.x で Docker-in-Docker を使ったときに ‘Docker daemon not running’ エラーでパイプラインが失敗する」
「HAProxy で大きなファイルを GitLab にプッシュするときの 502 エラーを解決する」
「自己署名インストールで Runner 登録が証明書エラーで失敗する場合の回避策」
「バックアップから復元した後の壊れた MR diff を修正する」
ドキュメントを更新または作成すべきとき
機能がどのように動作するよう設計されているか
ベストプラクティス、推奨事項
標準的な実装
ステップバイステップの実装ガイド
コンプライアンスとセキュリティ情報
アーキテクチャの決定事項
機能の説明
GitLab ドキュメントの例:
「Docker executor を使った GitLab Runner の構成」
「GitLab CI/CD パイプライン構成リファレンス」
「GitLab 用 SAML SSO のセットアップ」
「GitLab のバックアップと復元手順」
迷ったとき:
すぐに発生した顧客の Issue については、まずナレッジ記事から始めましょう。たとえ「ドラフト」記事だけでも、それを蓄積しましょう！ 顧客のコンテキストの中で蓄積してください。後からいつでもレビューできます。 標準的なガイダンスになったらドキュメントに昇格させましょう。 両方のリソースをリンクしましょう！ ナレッジ記事を作成したら、さらなる参照のためにドキュメントへリンクしてください。両者は互いに連携します！ 理解が深まるにつれてイテレーションしましょう。ナレッジは常に進化し更新されます。
bfd74782)