スタイルガイド

専用のスタイルガイドでチームの執筆ルールを定義し、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- という接頭辞は変更して構いません。ただし、ガイドの使用を始めたら固定してください。

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

スタイルガイドの設定は次の2か所から始められます:

サイトのサイドバーで、～の下に改善の下の スタイルガイドをクリックし、次に セットアップ.
未対応 設定 → スタイルガイド から設定します。

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

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

スタイルガイドを初めて開くと、GitBook は通常のコンテンツと同じように編集するものだと説明する短い導入文を表示します。

既存のスタイルガイドを使用する

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

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

テンプレートを選ぶ

GitBook では、開始用に3つのテンプレートを用意しています:

テンプレート

ファイルをアップロードする

すでに別のツールでスタイルガイドを管理しているなら、テンプレートから始める代わりにインポートできます:

設定画面で、 ファイルをアップロードする.
Markdown、HTML、DOCX、ZIP ファイルをドロップするか、参照して選択してください。
必要に応じて、 AI でインポートを強化 を有効にすると、インポートしたコンテンツを自動で洗練し、整えられます。
クリック インポートを開始.

URL からインポートする

スタイルガイドがオンラインで公開されている場合は、GitBook が直接インポートできます:

設定画面で、 URL からインポートする.
インポートしたいドキュメントのリンクを入力してください。
必要に応じて、 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 は変更リクエストの推奨レビュアーとして表示され、 スタイルガイドレビュー:

タグが付きます。 レビューを依頼.
変更内容のタイトルと説明を追加するか、生成をクリックして、変更内容から Agent に作成させます。
下に レビュアーの下の Request の横にある GitBook エージェント を選ぶと、変更リクエストのスタイルガイドレビューを実行します。人間のレビュアーも追加できますし、空欄のままにして組織内のすべてのレビュアーに通知することもできます。

Agent は変更内容をスタイルガイドと照らしてレビューし、違反を見つけた場合は変更リクエストに修正を要求します。その際、各フラグの根拠となったルールを引用します。

サイト全体でスタイルガイドチェックを実行する

変更ではなく既存のコンテンツを確認するには、スタイルガイド自体から スタイルガイドチェック を実行します。チェックでは、スペース内のすべてのページをルールと照らし合わせ、見つかった問題を変更リクエストに反映して、レビューできるようにします。

スタイルガイドを開いて、 チェックを実行.
確認するスペースを選びます。一度に最大3つのスペースを確認できます。
各スペースごとに GitBook Agent が開いた変更リクエストをレビューしてマージします。

GitBook Agent はスペースごとに1件の変更リクエストを開き、そのページを順に処理します。チェックで修正があった場合、その変更リクエストはレビュー可能としてマークされます。何も見つからなかった場合、その変更リクエストはアーカイブされるため、空の下書きが残ることはありません。

この スタイルガイドの編集後 タブには、サイトの構造に沿ってサイト内のスペースが一覧表示され、それぞれのスペースのチェック状態も表示されます。変更リクエストのステータス、チェック実行中のスピナー、最後に実行した日時、そして スタイルガイドは前回のチェック以降に編集されました バッジは、チェック後にガイドを変更したときに表示されます。行をクリックすると、その変更リクエストを開けます。

1つのスペースにつき、同時に1件のチェック変更リクエストしかありません。まだ開いている状態のスペースで再度チェックを実行すると、新しい変更リクエストを開く代わりに既存の変更リクエストが更新され、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 に内容の修正やスタイルガイドへの整合を依頼すると、修正が明確な箇所では番号付きルールを直接適用します。あるルールに2つの妥当な結果がある場合、Agent は推測せず、テキストをそのままにして提案として一覧に載せます。

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

Agent が決して触れないもの

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

コードブロック、インラインコード、コマンド出力、API や製品識別子の中のコンテンツ
直接引用と引用された資料
ルール自体の例外で除外されたテキスト
コンテンツの意味や事実
スタイルガイドに含まれていないルールでしか扱われないもの

一貫性

Agent は、たとえ「違う」と思われる場合でも、書かれたとおりにルールを適用します。コンテンツに合わせるためにルールを和らげたり、強めたり、解釈し直したりすることはありません。ルールの記述があいまいな場合、Agent は意図を勝手に作らず、その字義通りの意味で適用し、人によるレビュー向けの注記にあいまいさを記します。サイトにスタイルガイドが設定されていない場合、Agent は一般的な判断に頼るのではなく、代わりに作成を手伝うことを提案します。

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

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

最終更新 9 日前

役に立ちましたか？