ドキュメントの改善

ドキュメントの改善

チケットへの応答方法 ワークフローの ドキュメントセクション で説明されているとおり、包括的なドキュメントはチケット偏向のための強力なツールです。

応答に docs-first アプローチを取ることで、ドキュメントが非常に有用な 単一の情報源 であり続けることを保証できます。実際の問題に基づいて構築されたドキュメントのコーパスを構築することで、GitLab の顧客が必要な答えや解決策をキューに来る前に見つけるのを助けます。

これを念頭に置き、可能な限り、チケットへの応答の一部として該当するドキュメントへのリンクを含めてください。ドキュメントがまだ存在しない場合は、ドキュメント Issue またはドラフトのマージリクエストを 書き、応答にリンクを送信します。

以下に集約された情報は、ドキュメントに貢献する際に役立つはずです。

一般的なドキュメントガイドライン

変更を行う

ドキュメントガイドラインに従って名付けられた新しいブランチで、編集とコミットを行います。これらのガイドラインでは、ブランチ名は docs- で始まる必要があります（または ブランチ名スキームに記載されている他のオプションのいずれか）。

• 変更をコミットします。コミットメッセージが コミットメッセージガイドライン に従っていることを確認します。 ガイドラインに従わない場合、コミットがガイドラインと整合しているかをチェックする際に Danger Bot ジョブが失敗する可能性があります。失敗した場合は、ジョブのトレースを読み、新しいコミットまたは インタラクティブな rebase で問題を修正します。（rebase の方法がわからない場合はヘルプを求めてください！）

注: Git または GitLab 環境での作業の基本に慣れていない場合は、ドキュメントの変更を試みる前に Git および GitLab の基本トレーニングモジュール を完了してください。

スタイルガイドと Linting

• ドキュメントスタイルガイド をレビューします。
  • スタイルガイドを暗記する必要はありませんが、ドキュメントを書くときに準拠していることを確認するためにそれを参照することを忘れないでください。これにより、マージリクエストが迅速に承認されるよう支援します。
• トピックタイプページ もレビューすることを忘れないでください。特に トラブルシューティングセクション に注意を払います。
• 必須ではありませんが、パイプラインが失敗するのを防ぐため、ローカルエディターに docs linters をインストール することを強くお勧めします。または GDK を使用します。プラグインはコマンドラインからも使用できます。
  • markdownlint をセットアップします。
  • Vale をセットアップします。
  • 長い行を分割する のに役立つ、垂直ルーラーをセットアップ します。

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

• MR を作成する際は、docs MR ガイドライン に従います
• MR の説明には、関連するチケットや Issue へのリンクを必ず含めます
• 適切なラベルを追加します:
  • documentation（テンプレートが自動的にこのラベルを追加するはずですが、確認してください）。
  • グループ スコープラベル（迷った場合は、ドキュメントページの上部にリストされているはずです）
  • customer（チケットに関連する場合）
  • 注: ボットは、指定されない場合、ステージ、セクション、Support Team Contributions、および docs-only ラベルを追加します
• コードレビューガイドライン に従い、関連するテクニカルライター（TW）をレビュアーとして設定します。
  • ドキュメントテンプレートにはこれを見つける方法の指示がありますが、基本的にはドキュメントページのソース版の上部にあるメタデータ情報を参照します。
  • 編集したページに適切なテクニカルライターを見つけるには、Technical Writing Assignments を確認します。
  • Support dotfiles を使用している場合、find-technical-writer コマンドを使用して、特定のグループのテクニカルライターを素早く確認できます。
• MR を提出する前に、以下のオプションがチェックされていることを確認します:
  • Delete source branch when merge request is accepted.
  • Squash commits when merge request is accepted. 「Apply suggestion」機能はドキュメント MR で頻繁に使用されるため、このチェックボックスはマージ後にデフォルトブランチのきれいな履歴を維持するために不可欠です。

マージリクエストでテクニカルライターと協働する

• テクニカルライティングチームがあなたの貢献について尋ねる質問に、迅速に回答することを忘れないでください。
• ドキュメントプロセス を読みます。
  • 注: サポートは、TW に割り当てる前にドキュメント MR の技術的正確性を検証することが期待されています。迷ったときは、まずエンジニアから技術的レビューを受けてください。編集したページのメタデータ情報を使用して 適切なエンジニア を見つけます。
• マージ後レビューガイドライン を読みます。
  • サポートでは、緊急のドキュメント MR がある場合、たとえばドキュメントの修正をできるだけ早く公開する必要がある場合に、マージ後レビューオプションを使用するかもしれません。
  • 任意のページの「トラブルシューティングセクション」にある場合は、ガイドラインに従いますが、迅速にレビューしてマージするオンラインのサポートマネージャーに割り当てます。
  • そうでない場合は、必要な速さに応じて、#docs Slack チャンネル で共有して、そこにいる誰かにできるだけ早くレビューしてマージするよう依頼します。これは TW レビューが含まれるため、マージ後レビューを必要としません。
• docs deploy について読みます。重要なことは、ドキュメントがどのくらいの頻度でデプロイされるかに注目することです。
  • オプションで、ドキュメントサイトがどのように構築されるかを学ぶために、サイトアーキテクチャ情報 の残りを読みます。
• フィードバックを個人的に受け取らないことも忘れないでください - 私たちは皆、ドキュメントが正確で従いやすいものであることを望んでいるので、テクニカルライターからのすべてのフィードバックは、この目標を念頭に置いています！

Zendesk「Document this」ワークフロー

ドキュメント作成がより時間のかかる作業となる状況のため、完了する必要のあるドキュメントタスクを追跡するために、自動的に GitLab Issue トラッカー に Issue を作成するプロセスを設定しました:

• チケットに マクロ General::Document This を適用します。このマクロは create_doc_issue タグを適用し、記入するためのテンプレートを事前に入力します。
• タイトルと説明を変更してテンプレートを記入します。記入されたテンプレートの例:

CREATE DOCUMENTATION ISSUE
Title: Document how to use Y with an X
Description
There is a new cool feature Y that we released last month. It can be used with X to improve Z. We need to document how Y can be used with X.

## Test h2 header

We should remember to document:

1. requirements
1. how to enable
1. how to configure
1. how to troubleshoot

• 内部メモとして送信します。Issue が作成されると、doc_issue_created タグがチケットに追加されます。

このワークフローを使用して複数の Issue を作成する必要がある場合は、マクロをもう一度適用するだけです。 自動化により label_name[]=documentation&label_name[]=customer のラベルが付いた Issue が作成され、内部メモを送信したエージェントに割り当てられます。

注: 内部メモがトリガーによって正しく解析されるよう、必ずテンプレートを使用してください。

このワークフローは、内部メモを解析し、ドキュメント Issue を作成する Zendesk の HTTP ターゲット に送信する zendesk トリガー を使用して実装されています。

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