スタイルガイド
専用のスタイルガイドでチームの執筆ルールを定義し、共同作業者、人間でも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 の役割は、安定していることだけです。
スタイルガイドを作成する
スタイルガイドの設定は、次の2か所から始められます：
サイトのサイドバーの ツール、をクリックします スタイルガイドで、次に セットアップ.
開く 設定 → スタイルガイド から設定できます。
次に、開始方法を選びます（詳細は以下）：
組織内の既存のスタイルガイドを再利用する。
テンプレートを選ぶ — Starter、Google、または Microsoft。
すでにスタイルガイドがある場合は、ファイルをアップロードするか URL からインポートします。
スタイルガイドを初めて開くと、GitBook は、他のコンテンツと同じように編集できることを説明する短い案内を表示します。
既存のスタイルガイドを使う
組織内ですでに他の場所で使われているスタイルガイドがある場合、それらは、それを使っているサイトとともに設定画面の上部に表示されます。1つ選ぶと、次のことができます：
そのまま使う — ほかのサイトと共有して接続します。編集は、使用されているすべての場所に反映されます。
フォークする — このサイト専用のコピーを作成し（名前は
Styleguide - {site name}）、独立して発展させられます。
テンプレートを選ぶ
GitBook では、次の3つのテンプレートから始められます：
スターターテンプレート
自分の文体とルールをゼロから定義します。各セクションでは、そこに何を含めるべきか、なぜそれが必要かを説明し、あとは自分で埋めるための枠組みが用意されています。
Google スタイルガイド
開発者向けの、明確で正確かつ პროფეს゙ッショナルな文章。Google の開発者向けドキュメントのスタイルガイドをもとに生成されています。
Microsoft スタイルガイド
幅広い読者、つまり技術専門家でない読者も含めて、親しみやすく、シンプルで、人間味のある文章。Microsoft Writing Style Guide をもとに生成されています。
Google と Microsoft のテンプレートには、元のガイドからの適用可能なルールがあらかじめ入力されており、文体、語彙リスト、文法、書式、手順、アクセシブルな文章、インクルーシブな言語をカバーしています。そのまま使用できます。すべて編集可能です。テンプレートは出発点であり、契約ではありません。
"入力が必要です" セクションをカスタマイズする
すべてのテンプレートでは、カスタマイズが必要な箇所に 入力が必要です というヒントが付きます。スタイルガイドが使える状態になる前に、次の項目を埋めてください。通常は以下が含まれます：
テンプレートが反映しているベースガイド版のスナップショット日付（Google と Microsoft のテンプレート）
製品名とドキュメントの目的
誰がドキュメントを読み書きするのか、そしてガイドが何を対象にするのか
製品名、機能名、そしてチーム内で議論がある用語をワードリストに追加すること
担当者、レビュー頻度、変更提案の方法
意思決定ログの最初の記録
ヒントのない項目はすべて事前入力済みで、そのまま使用できます。まだ埋めていないプレースホルダールールは無効です。プレースホルダーを実際の内容に置き換えるまでは、Agent はそれを適用しません。
ファイルをアップロードする
別のツールですでにスタイルガイドを管理しているなら、テンプレートから始める代わりにそれをインポートできます：
セットアップ画面で、 ファイルをアップロードする.
Markdown、HTML、DOCX、または ZIP ファイルをドロップするか、ブラウズして選択します。
必要に応じて、 AI によるインポートの強化 を有効にして、インポートした内容を自動的に洗練し、整えます。
クリックして インポートを開始.
URL からインポートする
スタイルガイドがオンラインで公開されている場合、GitBook は直接インポートできます：
セットアップ画面で、 URL からインポートする.
インポートしたいドキュメントのリンクを入力してください。
必要に応じて、 AI によるインポートの強化 を有効にして、インポートした内容を自動的に洗練し、整えます。
GitBook は、入力した URL 配下の公開ページを最大 200 ページまでインポートします。たとえば、 website.com/docs/をインポートすると、 website.com/docs/articleは含まれますが、 website.com/other-parent/pageは含まれません。大きなサイトでは、より小さなサブパスを個別にインポートしてください。
スタイルガイドに何を書くか
スタイルガイドは、チーム内で誤りや不一致が起きやすい判断を記録してこそ、最も役立ちます。テンプレートは共通の構造を持ち、各セクションが異なる種類の文体上の論点を整理します：
はじめに： このガイドの目的と、ドキュメントの目的。目的が明示されたガイドは維持されますが、そうでないものは放置されがちです。
対象読者と範囲： 誰がドキュメントを読むのか、誰が書くのか、そしてガイドが何を対象にするのか。文体の議論の半分は、実は読者の議論です。ここで一度整理してください。
文体とトーン： 読者にどう語りかけるか、どれだけフォーマルか親しみやすいか、さらに句読点や短縮形のように機械的に確認できるものに対する適用可能なルール。
ワードリスト： 製品名、厳密な表記、推奨用語、そして決着済みの用語論争。チーム内で議論になった用語だけを記録し、項目は簡潔に保ちます。
文法と機械的ルール： 人称、時制、態の文レベルの既定値。例外欄はルールと同じくらい重要です。正当なテキストにフラグが立つのを防ぎます。
書式： 見出しの表記、UI 要素、リンク、コード、そしてリスト、ステッパー、ヒント、その他のブロックをいつ使うか。
執筆手順： 手順の形式、命令形の動詞、1手順につき1アクション。
エラーメッセージと失敗状態： 読者が最もストレスを感じる場面でのトーンルール。任意です。ドキュメントにエラー文がないなら削除してください。
アクセシブルな文章 、 インクルーシブな言語： ほとんどのチームがそのまま採用する、ほぼ普遍的で確認可能なルール。
コンテンツタイプとテンプレート： ページの種類。これにより、執筆者と Agent はページが従うべき構成を把握できます。多くのチームは次のようなフレームワークを使います Diátaxis.
所有権と更新： 担当者、レビュー頻度、変更提案の方法。誰にも管理されないガイドは、物語の中の存在になってしまいます。
意思決定ログ： 組織の記憶です。ルールを変えると、Agent が適用する内容も変わります。ログはその理由を記録するので、決着した議論は決着したまま保てます。ベースガイドから意図的に外れた内容はすべてここに記録してください。
スタイルガイドを編集する
スタイルガイドの編集は、他のドキュメントを編集するのと同じように行います：
GitBook では： 変更リクエストで変更を行い、準備ができたらマージします。
Git Sync では： スタイルガイドが GitHub または GitLab と同期されている場合は、リポジトリ内で Markdown として編集します。
スタイルガイドを開くには、 スタイルガイド サイトのサイドバーにあるエントリ、または 編集 のアクションを使用します 設定 → スタイルガイド.
スタイルガイドをサイト間で共有する
スタイルガイドは組織のものなので、複数のサイトが同じものを利用できます。編集エージェントはどこでも同じ執筆ルールを適用し、すべてのドキュメントが1つの文体にそろいます。
スタイルガイドを作成すると、GitBook は、まだ持っていない組織内の他のサイトにそれをリンクするよう提案します。前述のとおり、サイトを設定する際に、既存のスタイルガイド（共有またはフォーク済み）を接続することもできます。
組織内のすべてのスタイルガイドと、それぞれを使っているサイトを確認するには、 スタイルガイド 組織のサイドバーにあるエントリを開きます。
スタイルガイドの接続を解除する
サイトがそのスタイルガイドを使わないようにするには、 設定 → スタイルガイド に戻って 切り離すを開きます。接続を解除してもスタイルガイド自体は残り、他のサイトで使われ続ける場合があります。他のサイトから参照されていなければ、GitBook は完全削除を提案します。
スタイルガイドを活用する
スタイルガイドを用意したら、GitBook Agent に既存のドキュメントを一通り確認して、スタイルガイドに合わせるよう依頼してください。以後 Agent は、コンテンツを作成、編集、レビューするたびにスタイルガイドが守られているかを確認し、番号付きルールの違反はその ID とともにフラグ化し、番号なしのガイダンスは人間のレビュー向け提案として提示します。
変更に対してスタイルガイドレビューを実行する主な方法は2つあります：
レビューを依頼する前にページをレビューする
ページ編集中に、そのページがスタイルガイドに合っているかを Agent に確認してもらえます。以下を使ってください： スタイルガイドとの一貫性を確認 を Improve メニューで選ぶか、チャットで依頼します。Agent はページをレビューし、見つかった内容を要約したコメントを残します。
変更リクエストでスタイルガイドレビューを依頼する
サイトにスタイルガイドがあると、GitBook Agent は変更リクエストの推奨レビュアーとして表示され、 スタイルガイドレビュー:
変更リクエストで、 レビューを依頼.
をクリックして、変更にタイトルと説明を追加します。あるいは 生成 をクリックすると、Agent が変更内容からそれらを作成します。
次の項目の下で レビュアー、をクリックします Request の横にある GitBook Agent を指定して、変更リクエストのスタイルガイドレビューを実行します。人間のレビュアーを併せて追加することも、リストを空にして組織内のすべてのレビュアーに通知することもできます。
Agent は変更をスタイルガイドと照合してレビューし、違反を見つけた場合は変更リクエスト上で変更を要求し、各フラグの根拠となったルールを示します。
GitBook 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 に与えられるサイトレベルのカスタム指示を補完します。カスタム指示は短いサイト固有の指示であり、スタイルガイドは執筆ルールをまとめた完全で共有可能な文書です。
最終更新
役に立ちましたか？