ノートボックス：使用するタイミングと方法

ノートボックスは、読者が近くのコンテンツを解釈するのに役立つ文脈を分離しますが、読者が何をすべきか、どのような結果を期待すべきか、状況がどれほど深刻であるかを変更しません。

このレンダリング例は、ステップを追加せずに発生しうる質問を解決します。スキップした読者でもレポートを正しく使用できます。時刻の違いに気づいた読者は、不足している文脈を得て、ワークフローを変更せずに続行できます。

この要素が重要な理由

読者は視覚的な優先順位でページをスキャンします。境界で区切られたノートは、「この文脈は疑問を解決するかもしれないが、新しい指示ではない」と言います。そのシグナルは、余談を分類するために必要な労力を減らします。読者はメインの議論から一時的に離れ、説明を吸収し、プロセスが変更されたかどうかを疑問に思うことなく同じポイントに戻ることができます。

この要素は、その約束が信頼できる場合にのみ機能します。必須のステップ、セールスメッセージ、定義、警告、背景情報がすべてノートスタイルで表示される場合、ラベルは役に立ちません。読者はすべてのボックスを調べてその意味を発見しなければならず、通常の散文よりも多くの認知的負荷（情報処理に伴う精神的努力）がかかります。

重要度ラベルは繰り返しを通じて行動を教えます。無害な文脈に警告色が使用されると、読者は重要なシグナルに意味のある結果なしに繰り返し遭遇します。それを見過ごすことを学習します。次に本物の警告があったとき、誤報の履歴と競合することになります。警告スタイルをノートに誤用することは、1つのページを大げさにするだけでなく、サイト全体のリスク言語を弱めます。

機械にとって、型指定されたノートは明示的な境界と目的を提供します。コンテンツ移行ツールは、手順ステップにマージするのではなく、補足的な文脈としてブロックを保持できます。検索システムやAIエージェントは、ラベルと本文を含めてノートを抽出し、それが説明する主張に従属させることができます。その関係は、ページ固有のスタイルで青くされた段落からは回復するのが困難です。

抽出可能性はそれでも文章に依存します。「これは異なって見えるかもしれません」は、主題が欠落しているため、段落外では役に立ちません。「レポートのタイムスタンプは視聴者のローカル時刻ではなくUTCを使用します」は自己完結型です。要素作成ルール が優先されます：最初に目的に応じて文章を分類し、次に登録された要素を適用します。視覚的な強調が意味タイプを作成することはありません。

使用するタイミング

次の4つの条件がすべて真の場合にのみノートを使用します。

1. その文章が、近くの1つの記述、値、指示、例、またはシーケンスを明確にする。
2. それをスキップしても、必要なアクション、期待される結果、メインの主張の正しい解釈、またはリスクのレベルが変わらない。
3. その文脈が、そうでなければ理解を妨げるであろう読者のもっともな質問に答える。
4. その文章はラベルと共に抽出された場合でも意味を保つのに十分な自己完結性を持つ。

適切なノートの材料には、タイムゾーンの規則、命名の別名、メインテキストですでに暗示されているスコープの境界、バージョン間の無害なインターフェースの違い、または予想される表示状態の説明が含まれます。例：「ボタンは月額アカウントでは保存、年額アカウントでは適用と表示されます。両方とも同じ設定を送信します。」読者の行動と結果は変わりません。

「役立つ追加情報」は定義が広すぎるため、ニアミスが重要です：

• 次の段落を理解するために必要な事実は、メインの説明に属します。ノートに隠すと、必須の理解がオプションのように見えます。
• 前提条件は手順の前に属します。管理者アクセスなしで作業を開始できない場合、アクセスは補足的な文脈ではありません。
• 作業をより速く、より良くするオプションのテクニックはヒントボックス に属します。ヒントは結果の品質や効率を変えます。ノートは変えません。
• 削除、コスト、露出、傷害、または無効な作業を防ぐ条件は警告ボックス に属します。その目的は、害が生じる前に行動を変えることです。
• 用語の意味を確立する正式な定義は、定義要素またはメインの説明に属し、ノートには属しません。
• 引用は、それが支持する主張の隣に属します。主張が証拠に依存する場合、証拠は余談ではありません。
• プロモーション、サインアッププロンプト、または商品推奨はコールトゥアクションであり、情報ではありません。

分類が不明確な場合は無変更テストを使用します：「読者がこの事実を学んだ場合、行動、期待、決定、または安全対応を変更する必要がありますか？」はいの場合、それはノートではありません。いいえの場合、その事実が実際の曖昧さを解決するかどうかを尋ねます。解決しない場合は、削除するか、強調を作り出すのではなく通常の散文として保持します。

配置する場所

ノートは、明確にする完全なコンテンツブロックの直後に配置します。対象は段落、リスト項目、ステップ、テーブル、コードサンプル、または短いシーケンスの場合がありますが、対象はノートが表示される前に意味をなす必要があります。ノートは対象を分割することなく、補足的な文脈を提供します。

ノートがセクション全体に適用される場合、セクションの範囲を定義する冒頭段落の後に配置します。ノートの最初の文でその範囲を指定します。手順に適用される場合、アクションが変わらない場合にのみ導入段落の後かつ最初のステップの前に配置します。そうでなければ、コンテンツは前提条件または警告です。出力に関するノートは、出力が導入された後に配置し、数段落後ではありません。

ページあたり最大3つのノート、セクションあたり1つを使用します。3つは上限です。複数のノートが1つの文章の周りに集まる場合、メインテキストに説明が欠けているか、専用のサブセクションが必要である可能性があります。

ノートは次の場所に配置してはいけません：

• 見出しとその冒頭段落の間。
• 主張とそれを支持する証拠の間。
• 指示とその必須の成功確認の間。
• ヒント、警告、CTA、プロモーションバナー、または別のノートの直接隣。
• テーブルセル、FAQ回答、引用、コードブロック、アコーディオンパネル、または別のコールアウト内。
• ヒーロー内で単に視覚的興味のために配置すること。ただし、要素仕様が必須のライブ例をレンダリングする場合を除く。
• 対象がはるかに前に表示されたページの最後。

隣接がボックスのスタックを作成する場合は、ノートを散文に移動するか、セクションを再構成します。ノートを警告色に変更して衝突を解決しないでください。プレゼンテーションは不明瞭なコンテンツ関係を修復できません。

構造

レンダリングされたノートには、4つの可視または構造的な領域があります。

1. タイプラベル： 可視の「ノート」という単語。色やアイコンに依存せずにブロックを識別します。
2. オプションのタイトル： 「タイムゾーン」や「インターフェースラベル」など、文脈を名付ける短い事実に基づいたフレーズ。
3. 本文： 1つの自己完結した説明と、必要に応じて近くのコンテンツに結びつける文。
4. 隣接する対象： 明確にされている完全なブロックまたは名前付きシーケンス。配置がこの関係を伝えますが、作成されたテキストフィールドではありません。

境界線、背景、アイコン、スペーシング、タイプスタイルはレンダラーに属します。作成者は意味を提供し、色の指示や装飾的な記号は提供しません。

デザイン例

サポートされているバリエーションは、コンテンツとレスポンシブ動作をテストします。異なる重要度を作成するものではありません。

デフォルト： レンダラーが「ノート」を提供し、本文に1つの説明が含まれます。このフォームを最も頻繁に使用します。

カスタムタイトル： 事実に基づいたタイトルが主題を識別します。重要度を上げたり、コンポーネントのノートセマンティクスを置き換えたりしません。

最大2段落： 最初の段落が文脈を述べ、2番目が境界や無害な例外を解決します。より長い説明は通常のコンテンツになります。

インライン参照： 1つのインラインコード値または説明的リンクが対象を明確にできます。どちらもノートをドキュメンテーション内のドキュメンテーションにしてはいけません。

狭いビューポート： ラベル、タイトル、本文は読み取り順序を保持し、通常通り折り返し、境界線やアイコンなしでも理解可能です。

パラメーター

コンテンツモデルは、固定された意味タイプ、オプションの命名、本文、および近くのコンテンツとの関係を分離します。「ソース」は、作成者またはレンダラーが値を取得する場所を示します。

タイトルはオプションです。「ノート」で通常は十分だからです。ポータブルディレクティブの最初の見出しは、デフォルトの本文ルールの下でtitleにマップされる可能性がありますが、この要素では簡潔な属性形式が推奨されます。その他はすべてbodyにマップされます。現在のHugo実装は、位置タイプまたは名前付きtypeに加えて、オプションの名前付きtitleを受け入れます。位置パラメーターと名前付きパラメーターを混在させないでください。

構文とコード例

これらの形式は同じタイプ、タイトル、本文を持ちます。プラットフォームの表示は異なる場合がありますが、説明はノートのままでなければなりません。

ポータブルMarkdownディレクティブ

:::note{title="Time zone"}
Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.
:::

ディレクティブ名がタイプを提供し、属性がオプションのタイトルを提供し、囲まれたMarkdownが本文を提供します。

Hugoショートコード

{{< callout type="note" title="Time zone" >}}Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.{{< /callout >}}

この例は名前付きパラメーターのみを使用します。カスタムタイトルがない場合、位置形式 callout note が有効で、レンダラーが「ノート」ラベルを提供します。

WordPressブロックまたはショートコード

<!-- wp:amicited/note {"title":"Time zone"} -->
<p>Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.</p>
<!-- /wp:amicited/note -->

[note title="Time zone"]Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.[/note]

登録されたブロックが推奨されるWordPress実装です。ショートコードは、そのインストールが明示的にサポートしている場合に許容されます。インポートシステムは、ノートを警告に平坦化したり、その色から異なるタイプを推測したりしてはいけません。

例

適切：無害なインターフェースのバリエーション

これは適切です。もっともなインターフェースの質問に答えながら、同じアクションと結果を保持しているからです。両方のラベルを名前指定し、それぞれがどこに表示されるかを示し、同等の動作を確認しています。周囲の手順から抽出されても意味をなします。

不適切：情報として偽装された警告

注記 — ワークスペースの削除： ワークスペースを削除すると、そのレポートが完全に削除されます。続行する前に必要なレコードをエクスポートしてください。

これは不適切です。結果が不可逆的なアクションの前に行動の変更を必要とするからです。穏やかな言葉遣いと中立なラベルは、それを補足的なものにはしません。削除コントロールの前に配置された警告でなければならず、対象、結果、予防的アクションが明示的に記述されている必要があります。

もう一つの不適切なノートは、「エクスポートには必要な列がすべて含まれている必要があります」です。これは受入基準です。必要な列は指示または仕様テーブルに配置します。3つ目は、「最初にフィルターをかけてからエクスポートすると時間を節約できます」です。これは結果を改善する任意のアドバイスであり、したがってヒントです。視覚的なバリエーションよりも正しい分類が重要です。

スキーママークアップとアクセシビリティ

ノートボックスには専用のSchema.orgタイプやプロパティはありません。囲んでいるArticle、TechArticle、商品、またはその他の真実のページレベルスキーマ内の可視コンテンツのままです。それ用のスタンドアロンのJSON-LDオブジェクトを作成しないでください。ノートがステップを明確にする場合、その説明がステップの実行に必要な場合を除き、HowToStep.textから分離して保持します。必要な場合、それはそもそもオプションのノートコンテンツではありませんでした。

静的ノートはrole="alert"、ARIAライブリージョン、または強制アナウンスを必要としません。これらのメカニズムは緊急性や動的な変更を伝えますが、ノートは通常のドキュメント順序に存在し、緊急性のない文脈を持ちます。積極的なアナウンスはその重要度を誤って伝え、支援技術の出力をよりノイズの多いものにします。

可視ラベルは、背景画像、アイコンのみのツールチップ、またはCSS生成の装飾としてではなく、Document Object Model内のテキストとしてレンダリングします。リージョンロールを使用する場合は、そのアクセシブル名を可視ラベルまたはカスタムタイトルに接続します。読み取り順序はラベル、オプションのタイトル、本文です。色とアイコンはタイプを強化できますが、ヒントや警告との唯一の区別であってはいけません。

200%のテキストズームおよび狭いビューポートでは、本文は水平スクロールなしで折り返す必要があります。リンクには説明的なアンカーテキストが必要で、キーボードアクセス可能でなければなりません。インラインコードは高コントラストでも読み取り可能でなければなりません。重要な情報が構造スクリーンショットやアイコンの代替テキストのみに存在することはできません。

作成ルール

15〜60語を目標にします。ハードな最大値は2つまでの短い段落で90語です。より長い文章は通常、メインの説明への統合が必要です。極端に短いノートは、多くの場合、役立つ文脈のないラベルです。

ボックスごとに1つの説明を、穏やかで事実に基づいたトーンで記述します。最初の文で主題を述べ、次に無害な違いや境界を説明します。「「ちょっとしたことですが」のような会話的な埋め草ではなく、「タイムスタンプはUTCを使用します」のような正確な表現を好みます。解釈ルールの前に理由を示します：「アーカイブされたプロジェクトは過去のレポートに引き続き表示されるため、過去の日付範囲に合計が表示される場合があります。」

ノートには、プレーンな強調、最大2つの短いインラインコード値、および最大1つの説明的リンクを含めることができます。次のものを決して含めてはいけません：

• 必須のステップ、前提条件、検証ルール、成功基準、または復旧指示。
• 重大なリスク、不可逆的な結果、安全条件、法的指示、またはコスト開示。
• 速度、品質、正確性、または利便性を向上させることを目的とした任意のアドバイス。
• 完全な定義、主張を支持するために必要な証拠、またはソースリスト。
• 複数の独立した説明。
• テーブル、コードブロック、フォーム、ボタン、CTA、お客様の声、プロモーション、またはネストされた要素。
• ジョーク、警告的な言葉、装飾的な絵文字、または「重大」や「危険」などの言葉。

すべてのノートに「重要」というタイトルを付けないでください。重要性はこの要素の目的ではなく、その言葉は誤って警告の重大度に近づきます。「ノート」または事実に基づいた主題タイトルを使用します。不明瞭な散文を救済するためにノートを使用しないでください：最初にメインの説明を修復し、それでも真に補足的な曖昧さが残る場合にのみノートを保持します。

使用する投稿タイプ

postTypesフロントマターは、補足的な文脈が繰り返し発生する形式をリストします。包含は依然としてオプションです。テーブルは必要なスロットではなく、許可される役割と位置を定義します。

他の投稿タイプも、同じ無変更テストに合格する場合にノートを使用できます。リストされていることで視覚的リズムのために追加することが正当化されるわけではなく、リストされていないことで警告がノートになるわけでもありません。

QAチェックリスト

公開前にすべての項目を確認します：

• ブロックは近くの1つの文章を明確にし、アクション、結果、優先順位、解釈、またはリスクを変更しない。
• 文脈は対象を繰り返すのではなく、もっともな読者の質問に答える。
• 必須情報はメインコンテンツに残っている。
• ノートは完全な対象の直後、または名前付きシーケンスの範囲段落の後に配置されている。
• 見出しと導入、主張と証拠、指示と成功確認を分離していない。
• 警告、ヒント、CTA、バナー、または別のノートが直接隣に配置されていない。
• ページに3つ以上のノートがなく、セクションに1つ以上ない。
• 本文は15〜60語を目標とし、90語未満で、1つの説明を含む。
• 可視のテキストラベルは色、境界線、アイコン、画像なしでも機能する。
• コピーはラベルと共に抽出されても意味を保つ（周囲のスタイリングは不要）。
• ページ読み込み時に存在する場合、ボックスはアラートロールやライブリージョンを使用していない。
• Markdown、Hugo、WordPressのマッピングがタイプ、タイトル、本文、配置を保持している。
• Hugoパラメーターはすべて位置指定、またはすべて名前付きであり、混在していない。
• サポートされていないネストされたコンポーネント、コードブロック、テーブル、フォーム、プロモーションアクションが内部にない。
• スクリーンショットマーカーは存在しないアセットをレンダリングせずに将来のキャプチャを要求する。

FAQ

ノート、ヒント、警告の違いは何ですか？ ノートは何も変更せずに明確にします。ヒントはオプションの改善を提供します。警告は害、損失、コスト、露出、無効な作業を防ぐために行動を変えます。色ではなく、ブロックをスキップした場合の結果で分類します。

ノートボックスに必須情報を含めることはできますか？ いいえ。必須情報は、すべての読者が順番に遭遇するメインコンテンツに属します。ノートは無害なバリエーションを説明することができますが、それをスキップしてもタスクや解釈が誤りになることはありません。

ページに含めるノートボックスの数はいくつですか？ ページあたり最大3つ、セクションあたり1つを使用します。ほとんどのページはより少なくて済みます。ノートが繰り返される場合は、メインの説明を再構成する必要があることを示しています。

ノートボックスに警告色やアラートロールを使用すべきですか？ いいえ。警告のプレゼンテーションは重大な結果を知らせ、role="alert"は緊急の動的情報を知らせます。日常的な文脈にこれらを適用すると、人々は本当のシグナルを軽視するよう訓練され、支援技術ユーザーを誤解させます。

ノートボックスにリンクやコードを含めることはできますか？ 対象を直接明確にする場合に限り、1つの説明的リンクまたは最大2つの短いインラインコード値を含めることができます。コードブロック、テーブル、フォーム、またはマルチステップのドキュメンテーションにはメインコンテンツを使用します。

ノートは、読者の行動を変えずに本当の曖昧さを解決することで、その境界の価値を証明します。穏やかで、隣接し、自己完結し、アドバイスやリスクから視覚的に区別された状態を保ちます。