Do's and Don'ts: ペアで示すガイダンスルール

Do’s and Don’tsブロックは、推奨されるアクションと、同じスコープのミスをペアにし、そのミスがなぜ失敗するかを説明します。その価値はコントラストから生まれます。間違ったバージョンは誘惑的な失敗モードを明らかにし、正しいバージョンは読者に即座に代替案を提供します。

この表示例が制作モデルです。各行は1つの主題を同じ詳細レベルで扱います。「Don’t」は現実的なエラーとその結果を示し、「Do」は使用可能な修正を提供します。色やアイコンではなくラベルが区別を伝えます。

この要素が重要な理由

ルールは、読者が尊重すべき境界を視覚的に確認できると理解しやすくなります。肯定的な指示だけでは抽象的になりがちです。「具体的なエビデンスを使用する」だけでは、何が曖昧すぎるとみなされるのかがわかりません。否定的な指示だけでは摩擦が生じます。「根拠のない主張をしない」は何を避けるべきかを示しますが、次の行動が不明確です。この2つを組み合わせることで、境界が読者の行動可能な選択肢に変わります。

間違ったバージョンが教育的なのは、それが忙しい人が自然に書きそうなものに似ていることが多いからです。そのニアミスを示すことで、読者は自分の作業の中でもそれを認識できるようになります。理由も同様に重要です。「曖昧な言葉を使わない」は従順を要求するだけですが、「測定対象のタスクを明記せずに『速い』と書かないでください。読者は検証も比較もできないからです」は、新しい例にも応用可能な原則を教えます。

パリティとは、両側が同等の主題、数、詳細、編集上の重みをカバーすることを意味します。これにより、洗練された「Do」列が無関係な警告の山の隣に置かれるのを防ぎます。読者は1つのペアをスキャンし、コントラストを理解し、ページ上の別の場所の項目を覚えておく必要なく読み進められます。

機械抽出容易性とは、ソフトウェアが意味と関係性を保持したままコンテンツを抽出できる能力です。可視の見出し、リスト構造、行ごとに整列したペアにより、検索システムや回答エンジンは「価格については、プラン名と日付を明記し、日付のない数値は避ける。範囲が検証不可能だからである」のような文を抽出できます。両側に関連のない箇条書きが含まれていたり、理由がアイコンでしか示唆されていない場合、抽出は安全を担保する条件を失いながらも命令を保持してしまう可能性があります。

このブロックを選択する前に、要素作成ルール に従ってください。目的が外観に優先します。差し迫った危害について主に警告するコンテンツは警告のままであり、順序立てた手順はステップリストのままであり、有限の完了チェックはチェックリストのままです。色付きの2列があっても、それらの目的がDo’s and Don’tsに変わるわけではありません。

使用すべき場合

読者が推奨されるプラクティスと、もっともらしく結果を伴う誤りを区別する必要がある場合にこの要素を使用します。そのコントラストが、単一の指示よりも効果的に曖昧さを低減するはずです。適切な主題には、編集基準、実装規則、品質管理、デザインの振る舞い、データ処理、プロセス選択が含まれます。

以下の条件がすべて満たされるべきです：

1. 各誤りに対して責任ある代替アクションが存在する。
2. 誤りを避ける理由が1つの短い文で述べられる。
3. 項目は独立したガイダンスであり、順番に完了しなければならないステップではない。
4. 両側が同じ範囲と具体性のレベルを使用できる。

ニアミスケースは一般的です：

• メリット・デメリット： 長所と限界は1つの選択肢を評価します。Do’s and Don’tsは読者の行動を指示します。「無制限のプロジェクトを含む」はDoではなくメリットです。
• 警告： 重大または不可逆的な結果には、同等の重みのコンパニオン列ではなく、直接的な強調と対応策が必要です。
• チェックリスト： チェックリストは必要な作業が完了したかどうかを追跡します。未チェックの状態は「Don’t」ではありません。
• 比較表： 表は共有された基準に対して複数の選択肢を評価します。正しい行動と間違った行動を規定するものではありません。
• ビフォー・アフター： 2つの例が編集を示しても、再利用可能な行動ルールを表現していない場合があります。コントラストが一般的なプラクティスを教える場合にのみDo’s and Don’tsを使用してください。
• 恣意的なハウススタイル： 読者、システム、コンプライアンス、メンテナンス上の結果が説明できない場合は、その慣行をルールとして文書化し、代替案が誤りであるかのように装わないでください。

対立を作為的に作り出すためにブロックを使用しないでください。「明確に書くこと、不明瞭に書かないこと」は同じ抽象概念を言い換えているだけで何も教えません。間違った側は、認識できるほど魅力的で、診断できるほど具体的でなければなりません。

配置場所

ページがタスク、対象読者、およびガイダンスを理解するために必要な用語を定義した後にブロックを配置してください。ブロックは、それが凝縮する説明またはデモンストレーションの直後、または読者が行動する前の実践的な復習としてセクションの終わり近くに配置するのが適切です。

正確な配置ルール：

• 最も近い見出しで1つのトピックを導入します。すべてのペアは、遠くの段落からスコープを借りることなく、そのトピックの下で意味をなす必要があります。
• 基本原則の後、実装チェックリストまたは次のアクションの前にブロックを配置します。読者は完了を確認する前に理由を理解する必要があります。
• 繰り返しセクションでは、同じ位置とペア数の制限を使用します。ブロックを予測不能に移動すると、主題間のスキャンが難しくなります。
• ペアのリストはソース順序と視覚的レイアウトでまとめて保持します。説明用の散文はブロック全体の後に続けることができ、その両側を分割してはなりません。

別の2列の意思決定要素のすぐ隣に配置してはいけません。隣接するグリッドはどのラベルと行が一緒に属するかを不明瞭にするからです。「Do」と「Don’t」の間に、 testimonial、プロモーションバナー、フォーム、またはコールトゥアクションを配置しないでください。ルールが読者がまだ受け取っていない用語や文脈に依存する場合、それをページの最初の意味のあるコンテンツにしてはいけません。

構成

レンダリング凡例

1. トピック見出し： すべてのペアで共有される限定されたタスクまたは決定を名付けます。
2. Doラベル： 推奨される行動を識別する可視テキスト。アイコンや緑色の装飾は補足的なものです。
3. Don’tラベル： 避けるべき行動を識別する可視テキスト。句読点はローカライズされた編集形式を使用します。
4. アクション文： 観察可能な行動を名付ける1つの命令文または宣言文。
5. 理由： 指示を結果、失敗モード、または基本原則に結びつける1文。
6. ペアの関係： ソース順序とレイアウトにより、どの「Do」がどの「Don’t」に対応するかが保持されます。
7. オプションのソースノート： 事実要件を管理するポリシー、テスト、規制、またはエビデンスを識別します。

作成者はトピック、ペア、理由を提供します。レンダラーは、均等な表示、レスポンシブスタッキング、アクセシブルなラベル、および適切な場合の装飾アイコンを提供します。

デザイン例

以下のバリアントが完全なサポートセットです。これらは密度と配置を変更しますが、パリティや理由付けの契約は変更しません。

標準ペア行

ワイド画面では3〜7の水平方向に整列した行を使用します。各行には同じ主題に関する1つの「Do」と1つの「Don’t」が含まれます。

スタックモバイルペア

狭い幅では、各ペアをまとめて保持します：「Do」、次に「Don’t」、そして次のペア。すべての肯定的な項目をすべての否定的な項目の前にスタックすると対応関係が隠れてしまいます。

例主導バリアント

抽象的な命令よりも正確な文言、マークアップ、またはインターフェース動作がより有用な場合に使用します。各側は1つの短い例とそれに続く理由を示します。コードは選択可能なテキストのままです。

コンパクトレビューバリアント

基本となる理由がすぐ上ですでに説明されている場合にのみ使用します。理由は各項目に依然として表示されますが、別の段落ではなく短いフレーズで表示されます。

アイコンのみ、カルーセル、タブ、または独立して折りたたみ可能なバリアントを作成しないでください。これらはペアを分離し、一方の側を隠し、または比較をインタラクションに依存させます。

パラメータ

契約は、2つの無関係なリストではなくペアをモデル化します。「Source」はレンダラーが各値を取得する場所を示します。

最初の本文見出しは heading にマッピングされます。各ネストされた pair は両方のアクションと両方の理由を所有します。ソースモデルは、すべての肯定的な項目をすべての否定的な項目と別々に保存してはいけません。そうすると行の対応関係が配列の位置に依存し、編集時に壊れやすくなるからです。

構文とコード例

3つのフォーマットすべてが同じトピック、ペア順序、アクション、理由を保持します。アクションから理由を推論したり、自動的に肯定的な項目を作成したりしません。

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

:::dos-and-donts
## Writing comparison claims

::item{do="Name the exact plan and date checked" dont="Do not publish an undated price"}
### Do
Commercial facts change, so scope lets readers verify and reuse the claim.

### Don't
Readers cannot tell which plan or period an undated figure describes.
::

::item{do="Compare both products on the same criterion" dont="Do not compare unrelated capabilities"}
### Do
A shared measure makes the difference meaningful.

### Don't
Different criteria create the appearance of comparison without a valid choice.
::
:::

この要素はデフォルトのアイテムマッピングをオーバーライドします。親見出しが heading を、アイテム属性がアクションを提供し、最初の Do および Don't サブ見出しがその後のテキストを2つの理由にマッピングします。

Hugoショートコード

現在、本番環境のHugoショートコードはペアレコード契約を実装していません。それが存在するまでは、2つの無関係なリストヘルパーを使用する代わりに、ライブ例のようなセマンティックHTMLをレンダリングしてください。意図するアダプターは次のとおりです：

{{< dos-and-donts >}}
## Writing comparison claims

{{< do-dont-pair do="Name the exact plan and date checked" dont="Do not publish an undated price" >}}
### Do
Commercial facts change, so scope lets readers verify and reuse the claim.
### Don't
Readers cannot tell which plan or period an undated figure describes.
{{< /do-dont-pair >}}
{{< /dos-and-donts >}}

将来のレンダラーは、ペアレコードのリストを含む1つのラベル付き領域を生成する必要があります。2つの配列を作成し、レンダリング後にインデックスで結合してはいけません。

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

[dos_and_donts heading="Writing comparison claims" variant="standard"]
[pair]
[do action="Name the exact plan and date checked"]Commercial facts change, so scope lets readers verify and reuse the claim.[/do]
[dont action="Do not publish an undated price"]Readers cannot tell which plan or period an undated figure describes.[/dont]
[/pair]
[pair]
[do action="Compare both products on the same criterion"]A shared measure makes the difference meaningful.[/do]
[dont action="Do not compare unrelated capabilities"]Different criteria create the appearance of comparison without a valid choice.[/dont]
[/pair]
[/dos_and_donts]

カスタムWordPressブロックは各ペアを1つのレコードとして編集し、アクションまたは理由が欠けている場合は公開を防止する必要があります。

例

良い例：同等、実行可能、理由付けあり

各行のペアは共通の主題（プラン範囲、時間枠、エビデンスステータス）を共有しています。両方のアクションはドラフトでレビューできるほど具体的であり、各理由は何が問題になるかを説明しています。読者は正確な価格、製品、期間が変わっても原則を適用できます。

悪い例：2つの命令の寄せ集め

これは、列が無関係で不均等であるため失敗しています。「正確であること」には観察可能な完了条件がなく、「専門用語を使わない」は必要な用語と説明のない用語を区別せずに言語を禁止しています。否定的な項目のいずれも結果を述べておらず、空白のセルは作成者が4つのペアではなく2つのリストを作成したことを露呈しています。

このブロックを修正するには、1つのトピックを選択し、同等の行を作成します。用語については、ペアは次のようになります：「必要な専門用語は初出時に定義する。定義により初心者も議論を追うことができる」「正確な用語を曖昧な日常表現に置き換えない。置き換えによって意味が変わる可能性があるからである」。この修正はスローガンを押し付けるのではなく判断力を教えます。

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

Schema.orgは一般的な DoAndDont 型を提供していません。表示されるブロックは、囲む Article、TechArticle、HowTo、またはその他のページレベルの構造化データ内に収めてください（ただし、そのページが本当に該当する場合に限ります）。肯定的な項目を、順序立てられた手順を形成しない限り HowToStep レコードに変換せず、短い説明が含まれているという理由だけでペアを FAQPage として公開しないでください。

ネイティブの見出しとリストを使用します。1つの外側セクションは、トピック見出しからアクセシブルな名前を取得します。各ペアは、可視の「Do」ラベルと可視の「Don’t」ラベルを含む1つのリストアイテムまたはグループ化されたレコードである必要があります。ソース順序で各ペアを保持し、スクリーンリーダーユーザーが推奨事項とそれに対応する誤りを一緒に認識できるようにします。

色とアイコンは補足的なものです。緑色だけが「Do」の唯一のシグナルであってはならず、バツ印だけが「Don’t」の唯一のシグナルであってはなりません。装飾的なアイコンは空の代替テキストを受け取るか、支援技術から隠します。静的なブロックをフォーカス可能にしないでください。比較表で水平方向のオーバーフローが避けられない場合は、スクロール領域を包含してラベルを付けます。本番コンポーネントは代わりにペアをスタックする必要があります。

省略形「Don’t」は可視の編集コピーとして許容されます。コードフィールドでは、アポストロフィが属性名を複雑にする場合、ASCIIセーフな dont を使用します。レンダラーは保存されたアクションや理由を変更せずにラベルをローカライズします。

作成ルール

コマンドを確定する前に理由を書いてください。これにより、作成者は読者、システム、安全性、コンプライアンス、またはメンテナンス上の結果を特定することを余儀なくされます。弁護可能な理由が書けない場合、その禁止はガイダンスではなく好みである可能性があります。

3〜7ペアを使用します。各アクションは、実用的な場合は110文字以内で1つの観察可能な行動を表現する必要があります。各側に180文字以内の理由の文を1つ与えます。これらの制限により両側がスキャン可能になります。より長い修飾語は周囲の散文に属します。

5つの次元にわたってパリティを維持します：

• 主題： 両方のアクションが同じ決定または成果物に対処する。
• 抽象度： 正確なマークアップルールは「うまく書く」のような広範な格言とペアにできない。
• 文法： 並行する命令文または並行する宣言文を使用する。
• エビデンス： 同じ事実および情報源の基準を両側に適用する。
• 視覚的重み： どちらかの側がより多くのスペース、強調、詳細、またはデフォルトの可視性を受け取らない。

直接的で中立的な言葉を使用します。恥をかかせるような言葉（「価格を確認するのを忘れるのは不注意な書き手だけ」）よりも「検証されていない価格を公開しないでください」を選びます。皮肉、恐怖、絶対的な用語は避けてください。ただし、ルールが本当に絶対的であり、その範囲が明示されている場合は除きます。

以下のものを要素内に絶対に入れないでください：

• 片側を埋めたり数値的な対称性を強制するために追加された無関係なヒント。
• 結果、原則、または代替アクションのない禁止事項。
• 順序付けられた手順、チェックボックス、評価、判定、製品の利点と制限。
• 安全上重要な警告、法的免責事項、緊急指示、または不可逆的アクションの通知。
• 推薦文、長い引用、メディア、フォーム、コールトゥアクション、プロモーションボタン、またはクーポンコード。
• ネストされたアコーディオン、タブ、カルーセル、比較表、または別のDo’s and Don’tsブロック。
• 観察可能な行動ではなく道徳的失敗として枠付けられた、人々やグループに関する主張。

要件がポリシー、規制、テスト、または外部標準から来ている場合は、近くにソースノートを追加します。編集者が再確認できる程度に正確にルールを帰属させます。ブロックに長い引用装置を搭載しないでください。

使用する記事タイプ

postTypes フロントマター配列がこの使用状況マトリックスを駆動します。含めることで、記載された条件の下で要素が利用可能になります。そのタイプのすべてのページでブロックが必須になるわけではありません。

QAチェックリスト

• ブロックには、最も近い見出しから明確な1つの限定されたトピックがある。
• 基本原則がブロックの前に表示され、ペアがルールを強化し、発明しない。
• 3〜7の完全なペアがあり、「Do」と「Don’t」のアクション数が正確に同じである。
• すべてのペアが同じ主題、対象読者、範囲、具体性のレベルに対処している。
• すべての「Don’t」が現実的な誤りを特定し、その結果または失敗モードを説明している。
• すべての「Do」が実行可能な代替案を提供し、なぜ機能するかを説明している。
• どの項目もパートナーを単に否定したり、スローガンを繰り返したり、循環的な表現を使用していない。
• アクションには1つの行動が含まれ、110文字の目標に近い。
• 理由には1文が含まれ、180文字以内である。
• 両側が並行する文法、エビデンス基準、詳細、視覚的重みを使用している。
• 事実要件は、必要に応じてそのポリシー、規制、テスト、またはソースを特定している。
• ブロックには、ステップ、チェック状態、製品トレードオフ、重大な警告、プロモーション、フォーム、またはネストされた複雑な要素が含まれていない。
• 可視テキストは「Do」と「Don’t」と表示されており、色、位置、アイコンが唯一のシグナルではない。
• レスポンシブ出力は、すべての肯定的な項目をすべての否定的な項目の前にスタックするのではなく、各ペアをまとめて保持する。
• トピック見出しとペア構造は、プレーンテキストおよびスタイルやスクリプトが利用できない場合でも理解可能である。
• 構造化データは囲むページのみを記述し、Do’s and Don’tsのスキーマタイプを発明しない。
• スクリーンショットコメントは、実際のアセットが存在するまでレンダリングされないキャプチャ指示のままである。

FAQ

academyテンプレートは、このページの [[faq]] フロントマターに保存された5つの質問をレンダリングします。これらは、ペアの完全性、数値的パリティ、理由、構造化データ、項目数をカバーします。