スタイルガイド

専用のスタイルガイドスペースでチームの執筆ルールを定義し、人間の投稿者も GitBook Agent も一貫性を保てるようにします。

スタイルガイドは、チームのライティングのルールや慣例をまとめた専用のスペースです。サイト上のコンテンツをどのように書くべきかについての唯一の真実の स्रोतであり、声の調子、用語、書式、構成を定義します。

スタイルガイドは2つの対象に向けたものです。

• あなたのチーム: 執筆者とレビュー担当者が、どう書くべきかについて共有できる参照先を1つ持つことで、誰が編集してもドキュメントの一貫性が保たれます。
• GitBook Agent: Agentはあなたのスタイルガイドを読み、コンテンツの作成、編集、レビューを行うたびに従うべき真実のソースとして扱います。Agent自身の既定値や一般的なライティングの慣例は上書きされます。

スタイルガイドは早期アクセスです。 スタイルガイド機能は段階的に展開されています。まだ表示されない場合は、あなたの組織では有効になっていません。

GitBook Agentがスタイルガイドをどう使うか

GitBook Agentは、すべてのタスクでスタイルガイドの1ページ目全体をコンテキストに読み込みます。そのため、そのページが常に作業の指針になります。ほかのページは、目次を使って必要に応じて読み込みます。

主なルールは1ページ目に置いてください。 適用したいルールはすべてそこに入れ、必要に応じてAgentが参照できる詳細は追加ページにまとめてください。編集内容が常に優先されます。ルールを変更すればAgentはあなたの版に従い、ルールを削除すればAgentはそのルールの適用をやめます。

スタイルガイドは、Agentにとって唯一のルールのソースです。スタイルガイドがGoogleやMicrosoftのような上位ガイドを基盤として言及していても、その記述は人間の読者向けの背景情報であり、Agentへの指示ではありません。あなたにとって重要な慣例は、明記してください。

適用可能なルールとガイダンス

スタイルガイドはコンテンツを2つの階層に分けます。その違いは、ルールに番号付きIDがあるかどうかです。

• 番号付きルール （たとえば G-10 や MS-9）は、適用可能な階層です。Agentは違反を直接指摘し、IDを引用するので、どのフラグも正確なルールまでたどれます。
• 番号なしのガイダンス — たとえば声の調子の説明のようなもの — は、判断に委ねられる領域です。Agentは執筆時にそれを適用し、人間のレビュー向けの提案として示しますが、違反としてはフラグを立てません。

適用可能なルールを追加するには、そのルールがどこにあっても、現在の最大番号の次の番号を付けてください。IDは絶対に振り直したり再利用したりしないでください。過去のフラグや決定ログがそれらを参照しているためです。時間がたつと、番号はページ順と一致しなくなりますが、それは正常です。IDの役割は、安定していることだけです。

スターターテンプレートでは、 SG- という接頭辞は変更できますが、ガイドの使用を始めたら固定してください。

スタイルガイドを作成する

スタイルガイドの設定は、いくつかの場所から始められます。

• サイトのダッシュボードで ツールに移動し、 スタイルガイドをクリックしてから、 セットアップ.
• をクリックします。 サイト設定 → スタイルガイド を開き、そこから設定します。

次に、開始点を選びます（詳細は以下）。

• 組織内にある既存のスタイルガイドを再利用する。
• テンプレートを選ぶ — スターター、Google、またはMicrosoft。
• すでにスタイルガイドがある場合は、ファイルをアップロードするかURLからインポートする。

スタイルガイドを初めて開くと、GitBookは他のスペースと同じように編集できることを説明する短い導入を表示します。

既存のスタイルガイドを使う

組織内で別の場所ですでに使われているスタイルガイドがあれば、設定画面の上部に、そのスタイルガイドを使っているサイトとともに表示されます。それを選ぶと、次のことができます。

• そのまま使う — それを使っている他のサイトと共有されたまま接続する。編集は、使われているすべての場所に反映されます。
• フォークする — このサイト専用のコピーを作成する（名前は Styleguide - {site name}）。これなら独立して発展させられます。

テンプレートを選ぶ

GitBookでは、開始用に3つのテンプレートが用意されています。

テンプレート	おすすめ用途
スターターテンプレート	自分の声の調子とルールをゼロから定義する場合。各セクションでは、何を入れるべきか、その理由を説明し、自分で埋めるための土台が用意されています。
Googleスタイルガイド	開発者向けの、明確で正確かつ პროფესიონալな文章。Googleの開発者向けドキュメントのスタイルガイドをもとに生成されています。
Microsoftスタイルガイド	幅広い読者、技術の専門家ではない読者も含めて、温かく、シンプルで、人間味のある文章。Microsoft Writing Style Guideをもとに生成されています。

GoogleとMicrosoftのテンプレートには、出典ガイドにある適用可能なルールがあらかじめ入力されています。これには、声の調子、単語リスト、文法、書式、手順、アクセシブルな文章、包括的な言語が含まれ、そのまま使える状態です。すべて編集できます。テンプレートは出発点であり、契約ではありません。

GitBookは、出典ガイドが変わるとベーステンプレートを確認して更新するため、テンプレートは生成元のガイドに合わせて最新の状態に保たれます。

「入力が必要」セクションをカスタマイズする

各テンプレートでは、カスタマイズが必要な部分に 入力が必要 というヒントが付いています。スタイルガイドを使える状態にする前に、これらを埋めてください。通常、次の内容が含まれます。

• テンプレートが反映しているベースガイド版のスナップショット日付（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は含まれません。大きなサイトでは、より小さなサブパスごとに分けてインポートしてください。

スタイルガイドに何を書くか

スタイルガイドは、チーム内で間違えやすい、または一貫しにくい判断を記録するときに最も役立ちます。テンプレートは共通の構成を共有しており、各セクションが異なる種類のスタイル上の議論を整理します。

• はじめに: ガイドの目的と、ドキュメントの目的。目的が明記されたガイドは維持されます。目的がないものは放置されます。
• 対象読者と範囲: 誰がドキュメントを読み、誰が書くのか、そしてガイドが何をカバーするのか。スタイル上の議論の半分は、実は対象読者の議論の言い換えです。ここでまとめて解決してください。
• 声の調子とトーン: 読者への呼びかけ方、どのくらいフォーマルか親しみやすいか、さらに、句読点や短縮形のように機械的にチェックできるものについての適用可能なルール。
• 単語リスト: 製品名、正確な表記、大文字小文字の使い方、優先する用語、そして解決済みの用語上の議論。チームで議論になった用語だけを記録し、項目は簡潔に保ってください。
• 文法とメカニクス: 人称、時制、態の文レベルでの既定値。例外欄はルールと同じくらい重要です。これにより、正当な文章にAgentがフラグを立てるのを防げます。
• 書式: 見出しの大文字小文字、UI要素、リンク、コード、また、リスト、ステッパー、ヒント、その他のブロックをいつ使うか。
• 記述手順: 手順の形式、命令形、1ステップにつき1アクション。
• エラーメッセージと失敗状態: 読者が最もストレスを感じる場面に向けたトーンのルール。任意です。ドキュメントにエラー文が含まれないなら削除してください。
• アクセシブルな文章 と 包括的な言語: ほぼ普遍的で、チェック可能なルール。多くのチームがそのまま採用しています。
• コンテンツタイプとテンプレート: ページの種類。これにより、執筆者とAgentは、ページが従うべき構成を把握できます。多くのチームは次のようなフレームワークを使います。 Diátaxis.
• 担当と更新: 担当者、レビュー頻度、変更提案の方法。誰も所有していないガイドは、やがて事実でないものになっていきます。
• 決定ログ: 組織の記憶です。ルールを変更すると、Agentが適用する内容も変わります。ログはその理由を記録するので、決定済みの議論は決定済みのまま保たれます。ベースガイドから意図的に外した内容は、ここにすべて記録してください。

スタイルガイドを編集する

スタイルガイドはスペースなので、他のドキュメントと同じように編集します。

• GitBookでは: 変更リクエストで変更を加え、準備ができたらマージします。
• Git Syncを使う場合: スタイルガイドのスペースがGitHubまたはGitLabと同期されているなら、リポジトリ内のMarkdownとして編集します。

スタイルガイドを開くには、サイトのサイドバーにある スタイルガイド という項目、または 編集 アクションを使います。 サイト設定 → スタイルガイド.

サイト間でスタイルガイドを共有する

スタイルガイドは組織に属するため、複数のサイトが同じものを使えます。編集エージェントはどこでも同じライティングルールを適用し、すべてのドキュメントが1つの声の調子にそろいます。

スタイルガイドを作成すると、GitBookはまだスタイルガイドがない組織内の他のサイトに接続することを提案します。前述のように、サイトを設定するときに、既存のスタイルガイド（共有またはフォーク済み）を接続することもできます。

組織内のすべてのスタイルガイドと、それぞれを使っているサイトを確認するには、組織のサイドバーにある スタイルガイド という項目を開きます。

スタイルガイドの接続を解除する

サイトがそのスタイルガイドを使わないようにするには、 サイト設定 → スタイルガイド を開いて 接続解除を選びます。接続を解除してもスタイルガイドのスペースは残ります。他のサイトがまだ使っている可能性があります。ほかに参照しているサイトがなければ、GitBookは完全に削除することを提案します。

スタイルガイドを実践に移す

スタイルガイドを用意したら、GitBook Agentに既存のドキュメントを見直してスタイルガイドに合わせるよう依頼してください。以後、Agentはコンテンツの作成、編集、レビューのたびにスタイルガイドが守られているかを確認し、番号付きルール違反はID付きでフラグを立て、番号なしのガイダンスは人間のレビュー向けの提案として示します。

変更に対してスタイルガイドレビューを実行する主な方法は2つあります。

レビューを依頼する前にページをレビューする

ページ作業中に、Agentにそのページをスタイルガイドと照合するよう依頼できます。改善メニューの スタイルガイドと整合性を確認 を使うか、チャットで依頼してください。Agentはページをレビューし、見つかった内容を要約したコメントを残します。

変更リクエストでスタイルガイドレビューを依頼する

サイトにスタイルガイドがあると、GitBook Agentは変更リクエストのおすすめレビュアーとして表示され、 スタイルガイドレビュー:

1. というタグが付きます。 変更リクエストで.
2. 変更内容のタイトルと説明を追加してください。あるいは 生成 をクリックすると、Agentが変更内容から作成します。
3. 下の レビュアーに移動し、 の 横にある GitBook Agent の

依頼

を選ぶと、変更リクエストに対してスタイルガイドレビューが実行されます。人間のレビュアーを追加することも、空欄のままにして組織内の全レビュアーへ通知することもできます。

Agentは変更内容をスタイルガイドと照合し、違反が見つかると変更リクエスト上で修正を要求します。各フラグには、そのフラグを生んだルールが引用されます。

Agentが参照するルールは、スタイルガイドだけです

Agentは、上位ガイドのルール、一般的な優れた文体に関する知識、あるいは知っているどのスタイルガイドからも、あなたのスタイルガイドに書かれていないルールは適用しません。

Agentは、ルールの書き方についてもいくつかの点を尊重します。

• プレースホルダーのルールは無効です。 テンプレートページには、次のような角括弧付きのプレースホルダー文が含まれています。 [製品名] や [ルールを追加]。内容がまだプレースホルダー文のままのルールは、まだルールではありません。Agentはそれを適用しません。スタイルガイドの大部分がプレースホルダーなら、Agentは未入力が多く、適用は完了したルールに限定されると伝え、部分的な状態を完全なものとして扱いません。
• 例外は尊重されます。 多くのルールには例外があります（「行為主体が不明なら受動態でもよい」など）。列挙された例外に該当するテキストは違反ではありません。
• 番号がなくても明確なルールは有効です。 番号付きIDのないルールでも、「セミコロンは絶対に使わない」のように明確で検証可能な指示として書かれていれば、Agentはそれを適用し、IDの代わりに短い引用で示します。

Agentがレビューするとき

スタイルガイドレビュー中は、ページでも変更リクエストでも、Agentは問題を指摘するだけで、何も変更しません。各フラグには次が含まれます。

• ルール: スタイルガイド内のルールID（たとえば G-10）、またはIDがない場合はルールの短い引用。
• 場所: 問題が発生している見出しまたは行と、その問題のあるテキスト。
• 問題: 違反を1文で示したもの。
• 修正: そのまま貼り付けられる修正版テキスト。

レビューは 1回につき5件のフラグまでです。さらに問題がある場合、Agentは優先度の高い5件を報告し、最後に残りの問題があることを1行で示し、その件数も伝えます。フラグはカテゴリ順で並びます。まず用語と語彙、次に書式と句読点、その次に文法、最後に手順です。同一カテゴリ内ではページ順です。

番号なしのガイダンス — 声の調子、トーン、構造に関する助言 — は、フラグとして表示されることはありません。Agentが各回で追加するのは、判断に委ねられる階層の内容をまとめた「人間の確認が望ましい」という1つの統合メモまでです。

Agentが編集するとき

Agentにコンテンツの修正やスタイルガイドへの整合を依頼すると、修正が明確な場所では番号付きルールを直接適用します。あるルールに2通りの妥当な結果がある場合、Agentは推測せず、テキストを変更せずに提案として一覧に載せます。

編集後、AgentはルールIDごとにまとまった変更サマリーを件数付きで出力します。たとえば、「G-7: 'click on' を 'click' に置換、6件。」のようになります。判断階層の提案は、最後に別の短い一覧で表示されます。

Agentが一切触れないもの

レビューでも編集でも、Agentは次のものをフラグ付けしたり変更したりしません。

• コードブロック、インラインコード、コマンド出力、APIおよび製品識別子内のコンテンツ
• 直接引用と引用資料
• ルール自身の例外で除外されたテキスト
• コンテンツの意味や事実
• スタイルガイドにないルールだけで扱われる内容

一貫性

Agentは、たとえ「同意しない」場合でも、書かれたとおりにルールを適用します。内容に合わせてルールを弱めたり、強めたり、解釈し直したりすることはありません。ルールが書き方として曖昧な場合、Agentは文字どおりに解釈し、その曖昧さを人間のレビュー向けメモに記します。意図を勝手に作ることはありません。また、サイトにスタイルガイドが設定されていない場合、Agentは一般的な判断に頼るのではなく、代わりにスタイルガイド作成を提案します。

スタイルガイドとカスタム指示

スタイルガイドは、GitBook Agentに与えられるサイトレベルのカスタム指示を補完します。カスタム指示は、サイト固有の短い指示です。スタイルガイドは、あなたのライティングルールをまとめた、完全で共有可能なドキュメントです。