> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwo/styleguide.md). # スタイルガイド スタイルガイドには、チームの文章ルールと慣例がまとめられます。サイト上のコンテンツをどのように書くべきかについての唯一の信頼できる情報源であり、声とトーン、用語、書式、構成を定めます。 スタイルガイドは 2 つの対象に向けて役立ちます: * **あなたのチーム:** 書き手とレビュワーが、どう書くべきかの共通参照を 1 つ持てるため、誰が編集してもドキュメントの一貫性が保たれます。 * **GitBook Agent:** Agent はスタイルガイドを読み取り、コンテンツの作成・編集・レビューのたびに従うべき唯一の正本として扱います。Agent 自身の既定値や一般的な文章慣例よりも優先されます。 ### GitBook Agent がスタイルガイドをどのように使うか GitBook Agent は、すべてのタスクでスタイルガイドの最初のページ全体をコンテキストに読み込み、そのページを常に作業の指針にします。他のページは目次を使って、必要なときだけ読みます。 **主要なルールは最初のページに置いてください。** 適用したいルールはすべてそこに残し、必要に応じて Agent が参照できる詳細は追加ページに書きます。編集は常にあなたのものが優先されます。ルールを変更すれば Agent はあなたの版に従い、ルールを削除すれば Agent はその適用をやめます。 スタイルガイドは、Agent にとってルールの唯一の情報源です。たとえば Google や Microsoft のような上位ガイドを土台として言及していても、その記載は人間の読者向けの背景情報であり、Agent への指示ではありません。慣例として重要なら、明記してください。 #### 適用可能なルールとガイダンス スタイルガイドではコンテンツが 2 つの階層に分かれており、その違いはルールに番号付き ID があるかどうかです: * **番号付きルール** （たとえば `G-10` または `MS-9`）は、適用可能な階層です。Agent は違反を直接フラグし、ID を引用するため、どのフラグもそれを生んだ正確なルールまで追跡できます。 * **番号なしのガイダンス** — たとえば文体の説明のようなもの — は判断の対象です。Agent は文章作成時にこれを適用し、人間のレビュー用の提案として出しますが、違反としてフラグすることはありません。 適用可能なルールを追加するには、そのルールがどこにあっても、現在の最大番号の次を割り当てます。ID の再採番や再利用は絶対にしないでください — 過去のフラグや意思決定ログがそれらを参照しています。時間がたつと、番号がページ順と一致しなくなりますが、それは正常です。ID の役割は、安定していることだけです。 {% hint style="info" %} スターターテンプレートでは、 `SG-` という接頭辞は自由に変更できます。ただし、使い始めたら固定してください。 {% endhint %} ### スタイルガイドを作成する スタイルガイドの設定は、次の 2 か所から始められます: * サイトのサイドバーで、 **ツール**、クリックします **スタイルガイド**の次に **セットアップ**. * 開く **設定 → スタイルガイド** を開いて設定します。 次に、開始方法を選びます（詳細は以下）。 * 組織内の既存のスタイルガイドを再利用する。 * テンプレートを選ぶ — Starter、Google、または Microsoft。 * すでにスタイルガイドがある場合は、ファイルをアップロードするか URL からインポートする。 スタイルガイドを初めて開くと、GitBook は、他のコンテンツと同じように編集できることを説明する短いイントロを表示します。 #### 既存のスタイルガイドを使う 組織ですでに他の場所でスタイルガイドを使っている場合、設定画面の上部に、それらを使っているサイトとともに表示されます。1 つ選ぶと、次のことができます: * **そのまま使う** — それを使っている他のサイトと共有する形で接続します。編集は、使われているすべての場所に反映されます。 * **フォークする** — このサイト専用のコピーを作成します（名前は `Styleguide - {site name}`）で、独立して発展させられます。 #### テンプレートを選ぶ GitBook には、次の 3 つのテンプレートがあります:
テンプレート最適な用途
Starter テンプレート自分独自の声とルールをゼロから定義します。各セクションでは、何を書くべきか、なぜそこに書くのかを説明し、下地を自分で埋めていく構成になっています。
Google スタイルガイド開発者向けの、明快で正確、かつプロフェッショナルな文章。Google の開発者向けドキュメントのスタイルガイドをもとに生成されています。
Microsoft スタイルガイド幅広い読者、技術の専門家ではない読者も含めて、温かく、簡潔で、人間味のある文章。Microsoft Writing Style Guide をもとに生成されています。
Google と Microsoft のテンプレートには、元のガイドからの適用可能なルールがあらかじめ入力されています。内容は、声、語句一覧、文法、書式、手順、アクセシブルな書き方、包括的な言語をカバーしており、そのまま使えます。すべて編集可能です。テンプレートは出発点であって、契約ではありません。 {% hint style="info" %} GitBook は、元のガイドが更新されたときにベーステンプレートを見直して更新するため、テンプレートは生成元のガイドに追従した状態を保ちます。 {% endhint %} **「入力が必要です」セクションをカスタマイズする** 各テンプレートでは、カスタマイズが必要な部分に **入力が必要です** というヒントが付いています。スタイルガイドを使える状態にする前に、これらを埋めてください。通常、次の内容が含まれます: * テンプレートが反映しているベースガイド版のスナップショット日付（Google と Microsoft のテンプレート） * 製品名とドキュメントの目的 * 誰がドキュメントを読むのか、誰が書くのか、ガイドが何を対象にするのか * 製品名、機能名、チーム内で議論になった用語を word list に追加したもの * 担当者、レビュー頻度、変更の提案方法 * 意思決定ログの最初の項目 ヒントのない項目は、あらかじめ入力済みで、そのまま使えます。まだ埋めていないプレースホルダーのルールは無効です。実際の内容に置き換えるまで、Agent はそれらを適用しません。 #### ファイルをアップロード すでに別のツールでスタイルガイドを管理しているなら、テンプレートから始める代わりにインポートできます: 1. 設定画面で、 **ファイルをアップロード**. 2. Markdown、HTML、DOCX、または ZIP ファイルをドロップするか、参照して選択します。 3. 必要に応じて、 **AI でインポートを強化** を有効にして、インポートしたコンテンツを自動で洗練・整理します。 4. クリックして **インポートを開始**. #### URL からインポート スタイルガイドがオンラインで公開されている場合、GitBook は直接インポートできます: 1. 設定画面で、 **URL からインポート**. 2. インポートしたいドキュメントのリンクを入力してください。 3. 必要に応じて、 **AI でインポートを強化** を有効にして、インポートしたコンテンツを自動で洗練・整理します。 GitBook は、入力した URL 配下の公開ページを最大 200 ページまでインポートします。たとえば `website.com/docs/`をインポートすると、 `website.com/docs/article`は含まれますが、 `website.com/other-parent/page`は含まれません。大きなサイトでは、より小さなサブパスごとに分けてインポートしてください。 ### スタイルガイドに入れる内容 スタイルガイドは、チーム内で誤りや不一致が起きやすい判断を記録すると、最も役立ちます。テンプレートは共通の構成を持ち、各セクションで異なる種類のスタイル上の論点を整理します: * **はじめに:** ガイドの目的と、ドキュメントの目的。目的が明記されたガイドは維持されますが、目的のないものは放置されます。 * **対象読者と範囲:** 誰がドキュメントを読むのか、誰が書くのか、ガイドが何を対象にするのか。スタイルをめぐる議論の半分は、実は読者についての議論です。ここで一度決めてしまいましょう。 * **声とトーン:** 読者にどう呼びかけるか、どれくらいフォーマルか、どれくらい親しみやすいか。さらに、句読点や省略形のように機械的に判定できるものについては、適用可能なルールを設けます。 * **語句一覧:** 製品名、正確な表記、推奨用語、議論が決着した用語。チームで議論になった用語だけを記録し、項目は簡潔に保ちます。 * **文法と機械的ルール:** 人称、時制、態の文章レベルの既定値。例外欄はルールと同じくらい重要で、正当な文章に Agent がフラグを付けないようにします。 * **書式:** 見出しの表記、UI 要素、リンク、コード、そしてリスト、ステッパー、ヒント、その他のブロックをいつ使うか。 * **執筆手順:** 手順の形式、命令形の動詞、1 ステップ 1 アクション。 * **エラーメッセージと失敗状態:** 読者が最もストレスを感じる場面でのトーンルール。任意です。ドキュメントにエラー文言が含まれないなら削除してください。 * **アクセシブルな書き方** 、 **包括的な言語:** ほぼすべてのチームがそのまま採用できる、広く適用可能で確認しやすいルール。 * **コンテンツタイプとテンプレート:** ページの種類。これにより、書き手と Agent はページが従うべき構成を把握できます。多くのチームは、次のようなフレームワークを使います。 [Diátaxis](https://diataxis.fr/). * **担当と更新:** 担当者、レビュー頻度、変更の提案方法。誰も責任を持たないガイドは、現実から乖離していきます。 * **意思決定ログ:** 組織の記憶です。ルールを変えると Agent の適用内容も変わります。ログには、その理由を残すため、決着した議論はそのまま保てます。ベースガイドから意図的に逸脱した内容は、ここにすべて記録してください。 ### スタイルガイドを編集する スタイルガイドの編集方法は、他のドキュメントと同じです: * **GitBook では:** 変更リクエストで変更を行い、準備ができたらマージします。 * **Git Sync を使う場合:** スタイルガイドが GitHub または GitLab と同期されているなら、リポジトリ内で Markdown として編集します。 スタイルガイドを開くには、サイトのサイドバーにある **スタイルガイド** という項目、または **編集** の操作を使います **設定 → スタイルガイド**. ### サイト間でスタイルガイドを共有する スタイルガイドは組織に属するため、複数のサイトで同じものを使えます。編集エージェントはどこでも同じ文章ルールを適用し、すべてのドキュメントが一貫した声になります。 スタイルガイドを作成すると、GitBook は、まだスタイルガイドを持っていない組織内の他のサイトにリンクするよう提案します。前述のとおり、サイトの設定時に既存のスタイルガイドを接続することもできます（共有版でもフォーク版でも可）。 組織内のすべてのスタイルガイドと、それぞれを使っているサイトを確認するには、組織サイドバーの **スタイルガイド** 項目を開いてください。 #### スタイルガイドの接続を解除する サイトがそのスタイルガイドを使わないようにするには、 **設定 → スタイルガイド** に戻って **切り離す**を開きます。接続を解除してもスタイルガイド自体は残ります。他のサイトでまだ使われているかもしれません。ほかに参照しているサイトがなければ、GitBook は完全に削除する提案をします。 ### スタイルガイドを活用する スタイルガイドを設定したら、GitBook Agent に既存ドキュメントを見直させて、スタイルガイドに合わせるよう依頼してください。それ以降は、Agent がコンテンツを作成・編集・レビューするたびにスタイルガイドが守られているかを確認し、番号付きルールの違反はその ID でフラグを立て、番号なしのガイダンスは人間のレビュー用の提案として示します。 変更に対してスタイルガイドレビューを実行する主な方法は 2 つあります: #### レビューを依頼する前にページをレビューする ページを作業中に、そのページがスタイルガイドに合っているかを Agent に確認させられます。改善メニューの **スタイルガイドとの整合性を確認** を使うか、チャットで依頼してください。Agent はページをレビューし、見つかった内容を要約したコメントを残します。 #### 変更リクエストでスタイルガイドレビューを依頼する サイトにスタイルガイドがあると、GitBook Agent は変更リクエストのおすすめレビュワーとして表示され、 **スタイルガイドレビュー**: 1. 変更リクエストで、 **レビューを依頼**. 2. をクリックし、変更のタイトルと説明を追加してください。あるいは **生成** をクリックすると、Agent が変更内容から自動で書きます。 3. の下で **レビュワー**、クリックします **Request** の横の **GitBook Agent** としてスタイルガイドレビューを実行させます。人間のレビュワーを追加することもできますし、空欄のままにして組織内のすべてのレビュワーに通知することもできます。 Agent は変更をスタイルガイドと照合し、違反を見つけると変更リクエスト上で修正を依頼し、それぞれのフラグを生んだルールを引用します。 ### Agent がスタイルガイドをどのように適用するか GitBook Agent がスタイルガイドを扱うとき、その役割は一般的な文章改善ではなく、ルールへの適合です。正確で、保守的で、一貫した動作をするよう設計されており、同じコンテンツを同じスタイルガイドで確認すれば、常に同じ結果になります。 #### スタイルガイドはルールの唯一の情報源です Agent は、上位ガイドからのルール、一般的な優れた文体に関する知識、または別のスタイルガイドにあるルールを、あなたのスタイルガイドに書かれていない限り適用しません。 Agent は、ルールの書き方についてもいくつかの点を尊重します: * **プレースホルダーのルールは無効です。** テンプレートのページには、 `[Product name]` または `[Add a rule]`のような角括弧付きのプレースホルダー文が含まれています。中身がまだプレースホルダー文のルールは、まだルールではありません。Agent は適用しません。スタイルガイドの大部分がプレースホルダーなら、Agent はかなり未完成だと伝え、適用範囲は完成済みのルールに限られると説明します。部分的な合格を網羅的なものとして扱うことはありません。 * **例外は尊重されます。** 多くのルールには例外があります（「行為者が不明なら受動態でもよい」など）。記載された例外に当てはまる文章は違反ではありません。 * **ID がなくても明確なルールは有効です。** 番号付き ID のないルールでも、明確に確認可能な指示（「セミコロンは絶対に使わない」など）として書かれていれば、Agent はそれを適用し、ID の代わりに短い引用で示します。 #### Agent がレビューするとき ページでも変更リクエストでも、スタイルガイドレビュー中に Agent は問題をフラグしますが、内容自体は変更しません。各フラグには次が含まれます: * **ルール:** スタイルガイド内のルール ID（たとえば `G-10`）、または ID がない場合はルールの短い引用。 * **場所:** 問題が発生している見出しまたは行と、該当テキスト。 * **問題:** 違反を 1 文で示したもの。 * **修正:** そのまま貼り付けられる修正済みテキスト。 レビューは **1 回の実行あたり 5 件のフラグ**までです。それ以上の問題がある場合、Agent は優先度の高い上位 5 件を報告し、さらに問題があることを 1 行で通知して件数を示します。フラグはカテゴリ順で並べられます。まず語句選択と用語、次に書式と句読点、次に文法、最後に手順です。同じカテゴリ内ではページ順です。 番号なしのガイダンス — 声、トーン、構成上の助言 — は、フラグとして表示されません。最も高くても、Agent は判断階層に属する内容をまとめた 1 件の「人間が確認する価値あり」 नोटを 1 回の実行につき追加するだけです。 #### Agent が編集するとき Agent にコンテンツの修正やスタイルガイドへの整合を依頼すると、修正が明確な箇所では番号付きルールを直接適用します。ルールに 2 通りの妥当な結果がある場合、Agent は推測せずにテキストを変更せず、提案として一覧に載せます。 編集後、Agent はルール ID ごとにまとめた変更サマリーを件数付きで出力します。たとえば、「G-7: 'click on' を 'click' に置換、6 件。」のようになります。判断階層の提案は最後に別の短い一覧で表示されます。 #### Agent が決して触れないもの レビューでも編集でも、Agent は次の内容をフラグしたり変更したりしません: * コードブロック、インラインコード、コマンド出力、API および製品識別子内のコンテンツ * 直接引用と引用資料 * ルール自身の例外で除外されたテキスト * コンテンツの意味や事実 * スタイルガイドにないルールだけで扱われる内容 #### 一貫性 Agent は、たとえルールに「同意しない」場合でも、記載どおりに適用します。内容に合わせてルールを弱めたり、強めたり、解釈し直したりはしません。ルールの書き方に曖昧さがある場合、Agent は意図を勝手に補うのではなく、文字どおりに解釈し、その曖昧さを人間レビュー用のメモに記します。さらに、サイトにスタイルガイドが設定されていない場合、Agent は一般的な判断に頼るのではなく、代わりに新規作成を手伝う提案をします。 ### スタイルガイドとカスタム指示 スタイルガイドは、GitBook Agent に与えられるサイトレベルのカスタム指示を補完します。カスタム指示は短く、サイト固有の指示です。スタイルガイドは、文章ルールをまとめた完全で共有可能な文書です。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwo/styleguide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.