> 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/creating-content/styleguide.md). # スタイルガイド スタイルガイドには、チームの執筆ルールと慣例がまとめられます。サイト上のコンテンツをどのように書くべきかについての唯一の信頼できる情報源であり、文体やトーン、用語、書式、構成が含まれます。 スタイルガイドには2つの対象があります: * **あなたのチーム:** 執筆者とレビュー担当者が、どのように書くかについて共有できる参照先を1つ持てるため、誰が編集してもドキュメントの一貫性が保たれます。 * **GitBook Agent:** Agent はスタイルガイドを読み、コンテンツの作成、編集、レビューを行うたびに従うべき信頼できる情報源として扱います。Agent 独自の既定値や一般的な執筆慣例は上書きされます。 {% hint style="info" %} **スタイルガイドは早期アクセスです。** スタイルガイド機能は段階的に展開されています。まだ表示されない場合は、組織で有効になっていません。 {% endhint %} ### 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か所から始められます: * サイトのサイドバーで **ツール**を開き、 **Styleguide**をクリックしてから、 **セットアップ**. * をクリックします **設定 → Styleguide** を開き、そこから設定します。 次に、開始方法を選びます（詳細は後述）: * 組織にある既存のスタイルガイドを再利用する。 * テンプレートを選ぶ — Starter、Google、Microsoft。 * すでにスタイルガイドがある場合は、ファイルをアップロードするか、URL からインポートする。 スタイルガイドを最初に開くと、GitBook が「他のコンテンツと同じように編集します」と説明する短い案内を表示します。 #### 既存のスタイルガイドを使う 組織ですでに他の場所でスタイルガイドが使われている場合、セットアップ画面の上部に、それを使用しているサイトとともに表示されます。1つ選ぶと、次のことができます: * **そのまま使う** — それを共有利用し、使っている他のサイトにそのまま接続します。編集内容は、使用されているすべての場所に適用されます。 * **フォークする** — このサイト専用のコピーを作成します（名前は `Styleguide - {site name}`）で、独立して更新できます。 #### テンプレートを選ぶ GitBook には、開始用のテンプレートが3つあります:
テンプレートおすすめ用途
スターターテンプレート自分たちの文体とルールをゼロから定義する場合。各セクションには、何を入れるべきか、なぜ必要なのかが説明され、記入用のひな形が用意されています。
Google スタイルガイド開発者向け読者に対して、明確で正確、かつ מקצוע的な文章を書く場合。Google の開発者向けドキュメントのスタイルガイドから生成されています。
Microsoft スタイルガイド技術の専門家でない読者も含む幅広い読者に向けた、温かく、シンプルで、人間味のある文章を書く場合。Microsoft Writing Style Guide から生成されています。
Google と Microsoft のテンプレートには、元のガイドから取得した適用可能なルールがあらかじめ入力されています。内容は文体、用語集、文法、書式、手順、アクセシブルな文章、インクルーシブな表現をカバーしており、そのまま使えます。すべて編集可能です。テンプレートは出発点であり、契約ではありません。 {% hint style="info" %} GitBook は、元のガイドが更新されるとベーステンプレートを見直して更新するため、テンプレートは生成元のガイドに合わせて最新の状態に保たれます。 {% endhint %} **"入力が必要です" セクションをカスタマイズする** 各テンプレートでは、カスタマイズが必要な部分に **入力が必要です** というヒントが付いています。スタイルガイドを使える状態にする前に、これらを確認してください。通常、次の項目が含まれます: * テンプレートが反映しているベースガイド版のスナップショット日付（Google および Microsoft テンプレート） * 製品名とドキュメントの目的 * ドキュメントを読む人、書く人、そしてこのガイドが対象とする範囲 * 製品名、機能名、そしてチーム内で議論になった用語を用語集に追加する * 責任者、見直しの頻度、変更提案の方法 * 決定ログの最初の記録 ヒントのない項目は、すべてあらかじめ入力済みで、そのまま使えます。まだ埋めていないプレースホルダーのルールは無効です。プレースホルダーを実際の内容に置き換えるまで、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`は含まれません。大きなサイトでは、より小さなサブパスを個別にインポートしてください。 ### スタイルガイドに何を書くか スタイルガイドが最も役立つのは、チーム内で間違えやすい、または一貫しにくい判断を記録しているときです。テンプレートは共通の構成を持ち、各セクションが異なる種類のスタイル上の論点を整理します: * **はじめに:** このガイドの目的と、ドキュメントの目的。目的が明記されたガイドは維持されますが、ないものは放置されます。 * **対象読者と範囲:** 誰がドキュメントを読み、誰が書き、ガイドが何を対象とするか。スタイル上の議論の半分は、実は読者の議論です。ここで一度まとめて決めましょう。 * **文体とトーン:** 読者への呼びかけ方、フォーマルさや親しみやすさ、さらに句読点や縮約形のように機械的に判定できるものに対する適用可能なルール。 * **用語集:** 製品名、正確な表記、推奨用語、そして解決済みの用語上の議論。チーム内で議論になった用語だけを記録し、簡潔に保ちます。 * **文法とメカニクス:** 人称、時制、態の文レベルの既定値。例外の列はルールと同じくらい重要です。正当な文章にフラグが立つのを防ぎます。 * **書式:** 見出しの表記、UI 要素、リンク、コード、そしてリスト、ステッパー、ヒント、その他のブロックをいつ使うか。 * **記述手順:** 手順の形式、命令形の動詞、1手順につき1つの操作。 * **エラーメッセージと失敗状態:** 読者が最もストレスを感じる場面に対するトーンのルール。任意項目です。ドキュメントにエラーテキストが含まれないなら削除してください。 * **アクセシブルな文章** と **インクルーシブな表現:** ほぼすべてのチームがそのまま採用する、確認可能なルール。 * **コンテンツタイプとテンプレート:** ページの種類。これにより、執筆者と Agent はページが従うべき構成を把握できます。多くのチームは [Diátaxis](https://diataxis.fr/). * **所有者と更新:** 責任者、見直しの頻度、そして変更提案の方法。誰も所有していないガイドは、現実味を失っていきます。 * **決定ログ:** 組織の記憶です。ルールを変えると Agent が適用する内容も変わりますが、ログにはその理由が残るため、決着した議論は決着したまま保てます。ベースガイドから意図的に外れた内容は、ここにすべて記録してください。 ### スタイルガイドを編集する スタイルガイドの編集は、ドキュメントの他の部分を編集するのと同じです: * **GitBook では:** 変更リクエストで変更を行い、準備ができたらマージします。 * **Git Sync では:** スタイルガイドが GitHub または GitLab と同期されている場合、リポジトリで Markdown として編集します。 スタイルガイドを開くには、サイトのサイドバーにある **Styleguide** 項目、または **編集** の操作を使います **設定 → Styleguide**. ### サイト間でスタイルガイドを共有する スタイルガイドは組織に属するため、複数のサイトで同じものを利用できます。編集 Agent はどこでも同じ執筆ルールを適用し、すべてのドキュメントが1つの文体にそろいます。 スタイルガイドを作成すると、GitBook は、まだスタイルガイドを持っていない組織内の他のサイトに接続することを提案します。前述のように、サイトの設定時に既存のスタイルガイド（共有またはフォーク済み）を接続することもできます。 組織内のすべてのスタイルガイドと、それぞれを使用しているサイトを確認するには、組織のサイドバーにある **Styleguides** 項目を開きます。 #### スタイルガイドを切り離す サイトでスタイルガイドの使用をやめるには、 **設定 → Styleguide** を開いて **切り離す**をクリックします。切り離してもスタイルガイド自体は残り、他のサイトで引き続き使われる場合があります。ほかのサイトから参照されていなければ、GitBook は完全削除を提案します。 ### スタイルガイドを活用する スタイルガイドを設定したら、GitBook Agent に既存ドキュメント全体を見直させて、スタイルガイドに合わせるよう指示してください。以後 Agent は、コンテンツの作成、編集、レビューのたびにスタイルガイドが守られているか確認し、番号付きルールの違反にはその ID を付けてフラグを立て、番号なしのガイダンスは人によるレビュー向けの提案として提示します。 変更に対してスタイルガイドレビューを実行する主な方法は2つあります: #### レビューを依頼する前にページをレビューする ページ作業中に、Agent にそのページをスタイルガイドと照合させることができます。改善メニューの **スタイルガイドとの整合性を確認** を使うか、チャットで依頼してください。Agent はページをレビューし、見つかった点を要約したコメントを残します。 #### 変更リクエストでスタイルガイドレビューを依頼する サイトにスタイルガイドがあると、GitBook Agent は変更リクエストの推奨レビュアーとして表示され、 **スタイルガイドレビュー**: 1. というタグが付きます。 **変更リクエストで**. 2. 変更内容のタイトルと説明を追加するか、 **生成** をクリックして Agent に変更内容から書かせます。 3. の下で **レビュアー**を開き、 **依頼** の横の **GitBook Agent** に対して、変更リクエストのスタイルガイドレビューを実行させます。人間のレビュアーを追加することもできますし、リストを空にして組織内のすべてのレビュアーに通知することもできます。 Agent は変更をスタイルガイドと照合し、違反があれば変更リクエスト上で修正を要求し、各フラグの根拠となったルールを引用します。 ### Agent がスタイルガイドをどう適用するか GitBook Agent がスタイルガイドを扱うときの役割は、一般的な文章改善ではなく、ルールへの準拠です。正確で、保守的かつ一貫するよう設計されています。同じスタイルガイドに対して同じ内容を確認すれば、常に同じ結果になります。 #### スタイルガイドは唯一のルールの情報源です Agent は、上位ガイド、一般的な優れた文体の知識、あるいは自分が知っているどのスタイルガイドからも、あなたのスタイルガイドに書かれていないルールを適用することはありません。 Agent は、ルールの書き方についてもいくつかの点を尊重します: * **プレースホルダーのルールは無効です。** テンプレートのページには、次のような角括弧付きのプレースホルダーテキストが含まれます: `[製品名]` や `[ルールを追加]`。内容がまだプレースホルダーテキストのままのルールは、まだルールではありません。Agent は適用しません。スタイルガイドの大半がプレースホルダーの場合、Agent は未入力が多く、適用範囲は完了済みルールに限られると伝えます。部分的な状態を完全なものとして扱うことはありません。 * **例外は尊重されます。** 多くのルールには例外があります（「主体が不明な場合は受動態でも問題ない」など）。記載された例外に当てはまるテキストは違反ではありません。 * **明確なルールは ID がなくても有効です。** 番号付き ID がなくても、明確で確認可能な指示（「セミコロンは絶対に使わない」など）として書かれていれば、Agent はそれを適用し、ID の代わりに短い引用で参照します。 #### Agent がレビューするとき スタイルガイドレビューの間 — ページ上でも変更リクエスト上でも — Agent は問題を指摘しますが、内容は変更しません。各フラグには次が含まれます: * **ルール:** スタイルガイド内のルール ID（たとえば `G-10`）、または ID がない場合はルールの短い引用。 * **場所:** 問題が発生している見出しまたは行と、該当テキスト。 * **問題:** 違反内容を1文で述べたもの。 * **修正:** 貼り付け可能な修正済みテキスト。 レビューは **1回あたり5件のフラグ**が上限です。さらに問題がある場合、Agent は優先度の高い5件を報告し、最後に1行で追加の問題があることと件数を伝えます。フラグはカテゴリ別に順位付けされます。まず用語と語句、その次に書式と句読点、次に文法、最後に手順です。カテゴリ内ではページ順です。 番号なしのガイダンス — 文体、トーン、構成に関する助言 — はフラグとして表示されません。多くても、Agent は判断階層に関する内容をまとめた「人の目で確認する価値あり」というメモを1回のパスにつき1つだけ追加します。 #### Agent が編集するとき Agent に内容の修正やスタイルガイドへの整合を依頼すると、修正が明確な箇所には番号付きルールをそのまま適用します。1つのルールに対して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/creating-content/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.