Do's and Don'ts: Paired Guidance Rules

A do’s and don’ts block pairs a recommended action with a same-scope mistake and explains why the mistake fails. Its value comes from contrast: the wrong version exposes a tempting failure mode, while the right version gives the reader an immediate replacement.

This rendered example is the production model. Each row addresses one subject at the same level of detail. The “Don’t” names a realistic error and its consequence; the “Do” supplies a usable correction. Labels, not color or icons, carry the distinction.

Why this element matters

Rules are easier to understand when readers can see the boundary they are meant to respect. A positive instruction alone may feel abstract: “Use specific evidence” does not reveal what counts as too vague. A negative instruction alone creates friction: “Don’t make unsupported claims” says what to avoid but leaves the next move unclear. Placing the two together turns a boundary into a choice the reader can act on.

The wrong version is instructive because it often resembles what a busy person would naturally write. Showing that near miss helps the reader recognize it in their own work. The reason matters just as much. “Don’t use vague language” demands obedience; “Don’t write ‘fast’ without naming the measured task, because readers cannot verify or compare it” teaches a principle that transfers to new examples.

Parity means that both sides cover equivalent subjects, counts, detail, and editorial weight. It prevents a polished “Do” column from sitting beside a pile of unrelated warnings. Readers can scan one pair, understand the contrast, and continue without remembering an item from elsewhere on the page.

Machine extractability is the ability of software to isolate content while preserving its meaning and relationships. Visible headings, list structure, and row-aligned pairs let search systems and answer engines recover statements such as “For prices, name the plan and date; avoid undated figures because their scope is unverifiable.” If the two sides contain unrelated bullets or the reason is implied only by an icon, extraction can preserve the command while losing the qualification that makes it safe.

Follow the element writing rules before selecting this block. Purpose takes precedence over appearance. Content that primarily warns about immediate harm remains a warning; a sequence remains a step list; a finite set of completion checks remains a checklist. Two colored columns do not turn those purposes into do’s and don’ts.

When to use it

Use this element when readers need to distinguish a recommended practice from a plausible, consequential mistake. The contrast should reduce ambiguity more effectively than a single instruction. Suitable subjects include editorial standards, implementation conventions, quality controls, design behavior, data handling, and process choices.

All of these conditions should be true:

1. Each mistake has a responsible replacement action.
2. The reason for avoiding the mistake can be stated in one short sentence.
3. The items are independent guidance, not steps that must be completed in order.
4. Both sides can use the same scope and level of specificity.

Near-miss cases are common:

• Pros and cons: advantages and limitations evaluate one option. Do’s and don’ts instruct the reader’s behavior. “Includes unlimited projects” is a pro, not a do.
• Warning: a severe or irreversible consequence needs direct prominence and a response, not an equal-weight companion column.
• Checklist: a checklist tracks whether required work is complete. Its unchecked state is not a “Don’t.”
• Comparison table: a table evaluates several options against shared criteria. It does not prescribe correct and incorrect behavior.
• Before and after: two examples may show an edit without expressing a reusable behavioral rule. Use do’s and don’ts only when the contrast teaches a general practice.
• Arbitrary house style: if no reader, system, compliance, or maintenance consequence can be explained, document the convention as a rule instead of pretending the alternative is a mistake.

Do not use the block to manufacture opposition. “Do write clearly; don’t write unclearly” restates the same abstraction and teaches nothing. The wrong side must be tempting enough to recognize and specific enough to diagnose.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the block after the page has defined the task, audience, and any terms needed to understand the guidance. It belongs immediately after the explanation or demonstration it condenses, or near the end of a section as a practical review before the reader acts.

Exact placement rules:

• Introduce one topic in the nearest heading. Every pair must make sense under that topic without borrowing scope from a distant paragraph.
• Put the block after the governing principle and before an implementation checklist or next action. Readers should understand why before they verify completion.
• In repeated sections, use the same position and pair limits. Moving the block unpredictably makes it harder to scan across subjects.
• Keep the paired lists together in source order and visual layout. Explanatory prose may follow the complete block, not split its sides.

It may not sit directly beside another two-column decision element, because adjacent grids obscure which labels and rows belong together. Do not place a testimonial, promotional banner, form, or call to action between the “Do” and “Don’t” sides. Do not make it the first meaningful content on a page when the rules depend on terms or context the reader has not yet received.

Anatomy

Rendered legend

1. Topic heading: names the bounded task or decision shared by every pair.
2. Do label: visible text identifying recommended behavior; an icon or green treatment is supplemental.
3. Don’t label: visible text identifying behavior to avoid; punctuation uses the localized editorial form.
4. Action statement: one imperative or declarative instruction that names observable behavior.
5. Reason: one sentence connecting the instruction to a consequence, failure mode, or governing principle.
6. Pair relationship: source order and layout preserve which “Do” answers which “Don’t.”
7. Optional source note: identifies the policy, test, regulation, or evidence governing factual requirements.

The author supplies the topic, pairs, and reasons. The renderer supplies equal presentation, responsive stacking, accessible labels, and decorative icons where appropriate.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

The following variants are the complete supported set. They change density and arrangement, never the parity or reasoning contract.

Standard paired rows

Use three to seven horizontally aligned rows on wide screens. Each row contains one “Do” and one “Don’t” about the same subject.

Stacked mobile pairs

At narrow widths, keep each pair together: “Do,” then “Don’t,” then the next pair. Stacking all positive items before all negative items would hide correspondence.

Example-led variant

Use when exact language, markup, or interface behavior is more useful than an abstract command. Each side shows one short example followed by its reason. Code remains selectable text.

Compact review variant

Use only when the governing reasons have already been explained immediately above. The reason still appears in each item, but in a short phrase rather than a separate paragraph.

Do not create icon-only, carousel, tabs, or independently collapsible variants. They separate the pair, hide one side, or make comparison depend on interaction.

Parameters

The contract models pairs rather than two unrelated lists. “Source” describes where the renderer obtains each value.

The first body heading maps to heading. Each nested pair owns both actions and both reasons. The source model must not store all positive items separately from all negative items, because that makes row correspondence dependent on array position and easy to break during editing.

Syntax and code examples

All three formats preserve the same topic, pair order, actions, and reasons. They do not infer a reason from the action or create a positive item automatically.

Portable Markdown directive

:::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.
::
:::

This element overrides the default item mapping: the parent heading supplies heading; item attributes supply the actions; the first Do and Don't subheadings map their following text to the two reasons.

Hugo shortcode

No production Hugo shortcode currently implements the paired-record contract. Until one exists, render semantic HTML like the live example rather than using two unrelated list helpers. The intended adapter is:

{{< 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 >}}

The future renderer must produce one labelled region with a list of paired records. It must not create two arrays and zip them by index after rendering.

WordPress block or shortcode

[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]

A custom WordPress block should edit each pair as one record and prevent publication when an action or reason is missing.

Examples

Good: equivalent, actionable, and reasoned

The pairs share a subject in each row: plan scope, time window, and evidence status. Both actions are specific enough to review in a draft, and each reason explains what can go wrong. A reader can apply the principle even when the exact price, product, or period changes.

Bad: two piles of commands

This fails because the columns are unrelated and unequal. “Be accurate” has no observable completion condition, while “Never use jargon” prohibits language without distinguishing necessary terms from unexplained terms. None of the negative items states a consequence, and the blank cell exposes that the author created two lists rather than four pairs.

Repair the block by choosing one topic, then writing equivalent rows. For terminology, the pair could be: “Define a necessary specialist term on first use, because the definition lets newcomers follow the argument” and “Do not replace a precise term with a vague everyday phrase, because the substitution can change the meaning.” The correction teaches judgment instead of enforcing a slogan.

Schema markup and accessibility

Schema.org provides no general DoAndDont type. Keep the visible block inside the enclosing Article, TechArticle, HowTo, or other page-level structured data when that page genuinely qualifies. Do not convert the positive items into HowToStep records unless they form an ordered procedure, and do not publish the pairs as FAQPage merely because they contain short explanations.

Use native headings and lists. One outer section receives its accessible name from the topic heading. Each pair should be one list item or grouped record containing a visible “Do” label and a visible “Don’t” label. Preserve each pair in source order so a screen-reader user encounters the recommendation and its matching mistake together.

Color and icons are supplemental. Green cannot be the only signal for “Do,” and a cross cannot be the only signal for “Don’t.” Decorative icons receive empty alternative text or are hidden from assistive technology. Do not make a static block focusable. If horizontal overflow is unavoidable for an example table, contain and label the scroll region; the production component should stack pairs instead.

The contraction “Don’t” is acceptable as visible editorial copy. Code fields use ASCII-safe dont where apostrophes would complicate attribute names. Renderers localize the labels without changing the stored actions or reasons.

Writing rules

Write the reason before finalizing the command. This forces the author to identify the reader, system, safety, compliance, or maintenance consequence. If a defensible reason cannot be written, the prohibition may be preference rather than guidance.

Use three to seven pairs. Each action should express one observable behavior in 110 characters or fewer where practical. Give every side one reason sentence of no more than 180 characters. The limits keep the two sides scannable; longer qualifications belong in surrounding prose.

Maintain parity across five dimensions:

• Subject: both actions address the same decision or artifact.
• Altitude: a precise markup rule cannot be paired with a broad maxim such as “write well.”
• Grammar: use parallel imperatives or parallel declarative statements.
• Evidence: apply the same factual and sourcing threshold to both sides.
• Visual weight: neither side receives more space, emphasis, detail, or default visibility.

Use direct, neutral language. Prefer “Do not publish an unverified price” to shaming language such as “Only careless writers forget to verify prices.” Avoid sarcasm, fear, and absolute terms unless the rule is genuinely absolute and its scope is stated.

Never put these inside the element:

• Unrelated tips added to fill one side or force numerical symmetry.
• A prohibition without a consequence, principle, or replacement action.
• Ordered procedures, checkboxes, ratings, verdicts, or product advantages and limitations.
• Safety-critical warnings, legal disclaimers, emergency instructions, or irreversible-action notices.
• Testimonials, long quotations, media, forms, calls to action, promotional buttons, or coupon codes.
• Nested accordions, tabs, carousels, comparison tables, or another do’s and don’ts block.
• Claims about people or groups framed as moral failure rather than observable behavior.

When a requirement comes from a policy, regulation, test, or external standard, add a nearby source note. Attribute the rule precisely enough that an editor can recheck it; do not make the block carry a long citation apparatus.

Post types that use it

The postTypes frontmatter array drives this usage matrix. Inclusion makes the element available under the stated condition; it does not make the block mandatory on every page of that type.

QA checklist

• The block has one bounded topic that is clear from its nearest heading.
• The governing principle appears before the block, so the pairs reinforce rather than invent the rule.
• There are three to seven complete pairs and exactly the same number of “Do” and “Don’t” actions.
• Every pair addresses the same subject, audience, scope, and level of specificity.
• Every “Don’t” names a realistic mistake and explains its consequence or failure mode.
• Every “Do” provides an actionable replacement and explains why it works.
• No item merely negates its partner, repeats a slogan, or uses circular wording.
• Actions contain one behavior and stay near the 110-character target.
• Reasons contain one sentence and stay within 180 characters.
• Both sides use parallel grammar, evidence standards, detail, and visual weight.
• Factual requirements identify their policy, regulation, test, or source where necessary.
• The block contains no steps, check states, product trade-offs, severe warnings, promotion, forms, or nested complex elements.
• Visible text says “Do” and “Don’t”; color, position, and icons are not the only signals.
• Responsive output keeps each pair together instead of stacking all positive items before all negative items.
• The topic heading and pair structure remain understandable in plain text and when styles or scripts are unavailable.
• Structured data describes the enclosing page only and does not invent a do’s-and-don’ts schema type.
• Screenshot comments remain non-rendering capture instructions until real assets exist.

FAQ

The academy template renders the five questions stored in this page’s [[faq]] frontmatter. They cover pair completeness, numerical parity, reasons, structured data, and item count.