Zásady a chyby: Pravidla pro párová doporučení

Blok zásad a chyb páruje doporučenou akci s chybou ve stejném rozsahu a vysvětluje, proč tato chyba selhává. Jeho hodnota pramení z kontrastu: špatná verze odhaluje lákavý způsob selhání, zatímco správná verze dává čtenáři okamžitou náhradu.

Tento vykreslený příklad je produkčním modelem. Každý řádek se věnuje jednomu tématu na stejné úrovni podrobností. „Chyba“ pojmenovává realistický omyl a jeho důsledek; „Zásada“ poskytuje použitelnou opravu. Rozlišení nesou popisky, nikoli barva nebo ikony.

Proč na tomto prvku záleží

Pravidla jsou srozumitelnější, když čtenáři vidí hranici, kterou mají respektovat. Samotný pozitivní pokyn může působit abstraktně: „Používejte konkrétní důkazy“ neprozrazuje, co je příliš vágní. Samotný negativní pokyn vytváří tření: „Netvrďte nepodložená tvrzení“ říká, čemu se vyhnout, ale nenechává jasný další krok. Spojení obou dohromady přemění hranici na volbu, podle které může čtenář jednat.

Špatná verze je poučná, protože často připomíná to, co by zaneprázdněný člověk přirozeně napsal. Ukázání této téměř chyby pomáhá čtenáři rozpoznat ji ve vlastní práci. Důvod je stejně důležitý. „Nepoužívejte vágní jazyk“ vyžaduje poslušnost; „Nepište ‚rychle‘ bez uvedení měřeného úkolu, protože čtenáři to nemohou ověřit ani porovnat“ učí princip, který lze přenést na nové příklady.

Parita znamená, že obě strany pokrývají ekvivalentní témata, počty, podrobnosti a redakční váhu. Zabraňuje tomu, aby vedle sebe stál vyleštěný sloupec „Zásada“ a hromada nesouvisejících varování. Čtenáři mohou projít jeden pár, pochopit kontrast a pokračovat dál, aniž by si pamatovali položku z jiné části stránky.

Extrahovatelnost pro stroje je schopnost softwaru izolovat obsah při zachování jeho významu a vztahů. Viditelné nadpisy, struktura seznamu a řádkově zarovnané páry umožňují vyhledávacím systémům a odpověďovým engineům získat výroky jako „U cen uveďte plán a datum; vyhněte se nedatovaným údajům, protože jejich rozsah není ověřitelný.“ Pokud obě strany obsahují nesouvisející odrážky nebo je důvod vyjádřen pouze ikonou, extrakce může zachovat příkaz, ale ztratit kvalifikaci, která jej činí bezpečným.

Než vyberete tento blok, postupujte podle pravidel pro psaní prvků . Účel má přednost před vzhledem. Obsah, který primárně varuje před bezprostřední újmou, zůstává varováním; posloupnost zůstává seznamem kroků; konečná sada kontrol dokončení zůstává checklistem. Dva barevné sloupce nepromění tyto účely v zásady a chyby.

Kdy jej použít

Použijte tento prvek, když čtenáři potřebují rozlišit mezi doporučeným postupem a pravděpodobnou, důsledkovou chybou. Kontrast by měl snížit nejednoznačnost účinněji než samostatná instrukce. Vhodná témata zahrnují redakční standardy, implementační konvence, kontroly kvality, chování návrhu, zpracování dat a procesní volby.

Všechny tyto podmínky by měly platit:

1. Každá chyba má odpovědnou náhradní akci.
2. Důvod pro vyhnutí se chybě lze uvést v jedné krátké větě.
3. Položky jsou nezávislá doporučení, nikoli kroky, které musí být dokončeny v pořadí.
4. Obě strany mohou používat stejný rozsah a úroveň konkrétnosti.

Běžné jsou případy blízké chyby:

• Výhody a nevýhody: výhody a omezení hodnotí jednu možnost. Zásady a chyby instruují chování čtenáře. „Zahrnuje neomezené projekty“ je výhoda, nikoli zásada.
• Varování: závažný nebo nevratný důsledek vyžaduje přímou význačnost a reakci, nikoli doprovodný sloupec se stejnou vahou.
• Checklist: checklist sleduje, zda je požadovaná práce dokončena. Jeho nezaškrtnutý stav není „chyba“.
• Srovnávací tabulka: tabulka hodnotí několik možností podle společných kritérií. Nepředepisuje správné a nesprávné chování.
• Před a po: dva příklady mohou ukázat úpravu, aniž by vyjadřovaly opakovatelné pravidlo chování. Použijte zásady a chyby pouze tehdy, když kontrast učí obecný postup.
• Libovolný styl domu: pokud nelze vysvětlit žádný důsledek pro čtenáře, systém, shodu s předpisy nebo údržbu, zdokumentujte konvenci jako pravidlo namísto předstírání, že alternativa je chyba.

Nepoužívejte blok k vytvoření umělé opozice. „Pište srozumitelně; nepište nesrozumitelně“ opakuje stejnou abstrakci a nic neučí. Špatná strana musí být dostatečně lákavá k rozpoznání a dostatečně konkrétní k diagnostice.

Kam jej umístit

Blok umístěte poté, co stránka definovala úkol, publikum a všechny pojmy potřebné k pochopení doporučení. Patří bezprostředně za vysvětlení nebo demonstraci, kterou shrnuje, nebo blízko konce sekce jako praktické shrnutí před tím, než čtenář jedná.

Přesná pravidla umístění:

• Uveďte jedno téma v nejbližším nadpisu. Každý pár musí dávat smysl v rámci tohoto tématu, aniž by si vypůjčoval rozsah ze vzdáleného odstavce.
• Umístěte blok za hlavní princip a před implementační checklist nebo další akci. Čtenáři by měli nejprve pochopit proč, než ověří dokončení.
• V opakujících se sekcích používejte stejnou pozici a stejné omezení počtu párů. Nepředvídatelné přesouvání bloku ztěžuje procházení napříč tématy.
• Udržujte párové seznamy pohromadě ve zdrojovém pořadí i vizuálním rozvržení. Vysvětlující próza může následovat za celým blokem, nikoli rozdělovat jeho strany.

Nesmí být umístěn přímo vedle jiného dvousloupcového rozhodovacího prvku, protože sousedící mřížky zastírají, které popisky a řádky k sobě patří. Mezi strany „Zásada“ a „Chyba“ neumísťujte posudek, propagační banner, formulář ani výzvu k akci. Neumísťujte jej jako první smysluplný obsah na stránce, pokud pravidla závisí na pojmech nebo kontextu, které čtenář dosud neobdržel.

Anatomie

Vysvětlivky vykreslení

1. Nadpis tématu: pojmenovává ohraničený úkol nebo rozhodnutí sdílené všemi páry.
2. Popisek Zásada: viditelný text identifikující doporučené chování; ikona nebo zelené zvýraznění je doplňkové.
3. Popisek Chyba: viditelný text identifikující chování, kterému se vyhnout; interpunkce používá lokalizovanou redakční formu.
4. Výrok akce: jeden rozkazovací nebo oznamovací pokyn, který pojmenovává pozorovatelné chování.
5. Důvod: jedna věta spojující pokyn s důsledkem, způsobem selhání nebo hlavním principem.
6. Vztah páru: zdrojové pořadí a rozvržení zachovává, která „Zásada“ odpovídá které „Chybě“.
7. Volitelná poznámka ke zdroji: identifikuje politiku, test, předpis nebo důkazy, které jsou základem věcných požadavků.

Autor dodává téma, páry a důvody. Renderovací engine zajišťuje stejnou prezentaci, responzivní skládání, přístupné popisky a dekorativní ikony tam, kde je to vhodné.

Příklady návrhů

Následující varianty jsou úplnou podporovanou sadou. Mění hustotu a uspořádání, nikoli paritu nebo smluvní závazek ohledně zdůvodnění.

Standardní párové řádky

Použijte tři až sedm horizontálně zarovnaných řádků na širokých obrazovkách. Každý řádek obsahuje jednu „Zásadu“ a jednu „Chybu“ na stejné téma.

Skládané mobilní páry

Při úzkých šířkách udržujte každý pár pohromadě: „Zásada“, poté „Chyba“, poté další pár. Skládání všech pozitivních položek před všechny negativní by skrylo vzájemnou korespondenci.

Varianta vedená příkladem

Použijte, když je přesný jazyk, značkování nebo chování rozhraní užitečnější než abstraktní příkaz. Každá strana ukazuje jeden krátký příklad následovaný svým důvodem. Kód zůstává vybíratelným textem.

Kompaktní varianta shrnutí

Použijte pouze tehdy, když byly hlavní důvody již vysvětleny bezprostředně výše. Důvod se stále objevuje u každé položky, ale v krátké frázi namísto samostatného odstavce.

Nevytvářejte varianty pouze s ikonami, karuselem, záložkami nebo nezávisle sbalitelnými prvky. Oddělují páry, skrývají jednu stranu nebo činí srovnání závislé na interakci.

Parametry

Smlouva modeluje páry, nikoli dva nesouvisející seznamy. „Zdroj“ popisuje, odkud renderovací engine získává každou hodnotu.

První nadpis v těle se mapuje na heading. Každý vnořený pair vlastní obě akce i oba důvody. Zdrojový model nesmí ukládat všechny pozitivní položky odděleně od všech negativních, protože by tím byla korespondence řádků závislá na pozici v poli a snadno by se během editace porušila.

Syntaxe a příklady kódu

Všechny tři formáty zachovávají stejné téma, pořadí párů, akce a důvody. Neodvozují důvod z akce ani nevytvářejí pozitivní položku automaticky.

Přenosná direktiva 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.
::
:::

Tento prvek přepisuje výchozí mapování položek: nadřazený nadpis dodává heading; atributy položek dodávají akce; první podnadpisy Do a Don't mapují svůj následující text na oba důvody.

Hugo shortcode

Žádný produkční Hugo shortcode v současnosti neimplementuje smlouvu párových záznamů. Dokud nebude existovat, vykreslujte sémantické HTML jako v živém příkladu namísto použití dvou nesouvisejících pomocných prvků seznamu. Zamýšlený adaptér je:

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

Budoucí renderovací engine musí vytvořit jednu popsanou oblast se seznamem párových záznamů. Nesmí vytvořit dvě pole a spojovat je podle indexu po vykreslení.

WordPress blok nebo 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]

Vlastní WordPress blok by měl editovat každý pár jako jeden záznam a zabránit publikaci, když chybí akce nebo důvod.

Příklady

Dobrý: ekvivalentní, proveditelný a odůvodněný

Páry sdílejí téma v každém řádku: rozsah plánu, časové okno a stav důkazů. Obě akce jsou dostatečně konkrétní pro kontrolu v návrhu a každý důvod vysvětluje, co se může pokazit. Čtenář může princip aplikovat, i když se přesná cena, produkt nebo období změní.

Špatný: dvě hromady příkazů

Toto selhává, protože sloupce nesouvisí a nejsou vyvážené. „Buďte přesní“ nemá pozorovatelnou podmínku dokončení, zatímco „Nikdy nepoužívejte žargon“ zakazuje jazyk, aniž by rozlišovalo mezi nezbytnými a nevysvětlenými pojmy. Žádná z negativních položek neuvádí důsledek a prázdná buňka odhaluje, že autor vytvořil dva seznamy namísto čtyř párů.

Opravte blok výběrem jednoho tématu a následným napsáním ekvivalentních řádků. Pro terminologii by pár mohl být: „Definujte nezbytný odborný termín při prvním použití, protože definice umožňuje nováčkům sledovat argumentaci“ a „Nenahrazujte přesný odborný termín vágním každodenním slovem, protože tato náhrada může změnit význam.“ Oprava učí úsudku namísto prosazování sloganu.

Značkování Schema a přístupnost

Schema.org neposkytuje obecný typ DoAndDont. Udržujte viditelný blok uvnitř obklopujícího typu Article, TechArticle, HowTo nebo jiné strukturované údaje na úrovni stránky, pokud tato stránka skutečně splňuje podmínky. Nepřevádějte pozitivní položky na záznamy HowToStep, pokud netvoří seřazený postup, a nezveřejňujte páry jako FAQPage pouze proto, že obsahují krátká vysvětlení.

Používejte nativní nadpisy a seznamy. Vnější sekce získává svůj přístupný název z nadpisu tématu. Každý pár by měl být jedna položka seznamu nebo seskupený záznam obsahující viditelný popisek „Zásada“ a viditelný popisek „Chyba“. Zachovejte každý pár ve zdrojovém pořadí, aby uživatel čtečky obrazovky narazil na doporučení a jeho odpovídající chybu společně.

Barva a ikony jsou doplňkové. Zelená barva nemůže být jediným signálem pro „Zásadu“ a křížek nemůže být jediným signálem pro „Chybu“. Dekorativní ikony obdrží prázdný alternativní text nebo jsou skryty před asistenčními technologiemi. Nečinte statický blok zaměřitelným. Pokud je horizontální přetečení u příkladové tabulky nevyhnutelné, omezte a popište oblast rolování; produkční komponenta by měla místo toho páry skládat.

Zkratka „Don’t“ je přijatelná jako viditelný redakční text. Pole kódu používají ASCII-bezpečné dont tam, kde by apostrofy komplikovaly názvy atributů. Renderovací engine lokalizuje popisky, aniž by měnil uložené akce nebo důvody.

Pravidla psaní

Napište důvod před dokončením příkazu. To nutí autora identifikovat důsledek pro čtenáře, systém, bezpečnost, shodu s předpisy nebo údržbu. Pokud nelze napsat obhajitelný důvod, může být zákaz spíše preferencí než doporučením.

Použijte tři až sedm párů. Každá akce by měla vyjadřovat jedno pozorovatelné chování v 110 znacích nebo méně, kde je to praktické. Ke každé straně uveďte jednu větu důvodu o maximálně 180 znacích. Limity udržují obě strany přehledné; delší kvalifikace patří do okolní prózy.

Udržujte paritu v pěti dimenzích:

• Předmět: obě akce se týkají stejného rozhodnutí nebo artefaktu.
• Úroveň: přesné pravidlo značkování nelze párovat s širokou maximou jako „pište dobře.“
• Gramatika: používejte paralelní rozkazovací způsob nebo paralelní oznamovací věty.
• Důkazy: aplikujte stejnou věcnou a zdrojovou úroveň na obě strany.
• Vizuální váha: žádná strana nezískává více prostoru, důrazu, podrobností nebo výchozí viditelnosti.

Používejte přímý, neutrální jazyk. Preferujte „Nezveřejňujte neověřenou cenu“ před zahanbujícím jazykem jako „Jen nedbalí autoři zapomínají ověřit ceny.“ Vyhněte se sarkasmu, strachu a absolutním termínům, pokud pravidlo není skutečně absolutní a jeho rozsah je uveden.

Nikdy do prvku nevkládejte:

• Nesouvisející tipy přidané k vyplnění jedné strany nebo vynucení numerické symetrie.
• Zákaz bez důsledku, principu nebo náhradní akce.
• Seřazené postupy, zaškrtávací políčka, hodnocení, verdikty nebo výhody a omezení produktu.
• Bezpečnostně kritická varování, právní vyloučení odpovědnosti, nouzové instrukce nebo upozornění na nevratné akce.
• Posudky, dlouhé citace, média, formuláře, výzvy k akci, propagační tlačítka nebo kuponové kódy.
• Vnořené akordeony, záložky, karusely, srovnávací tabulky nebo jiný blok zásad a chyb.
• Tvrzení o lidech nebo skupinách rámovaná jako morální selhání namísto pozorovatelného chování.

Pokud požadavek pochází z politiky, předpisu, testu nebo externího standardu, přidejte poblíž poznámku ke zdroji. Přiřaďte pravidlo dostatečně přesně, aby jej editor mohl znovu zkontrolovat; nenechávejte blok nést dlouhý citační aparát.

Typy příspěvků, které jej používají

Pole postTypes v front matter řídí tuto matici použití. Zahrnutí zpřístupňuje prvek za uvedené podmínky; nečiní blok povinným na každé stránce daného typu.

QA checklist

• Blok má jedno ohraničené téma, které je zřejmé z jeho nejbližšího nadpisu.
• Hlavní princip se objevuje před blokem, takže páry pravidlo posilují, nikoli vytvářejí.
• Existuje tři až sedm úplných párů a přesně stejný počet akcí „Zásada“ a „Chyba“.
• Každý pár se věnuje stejnému předmětu, publiku, rozsahu a úrovni konkrétnosti.
• Každá „Chyba“ pojmenovává realistický omyl a vysvětluje jeho důsledek nebo způsob selhání.
• Každá „Zásada“ poskytuje proveditelnou náhradu a vysvětluje, proč funguje.
• Žádná položka pouze nepopírá svého partnera, neopakuje slogan ani nepoužívá kruhové vyjádření.
• Akce obsahují jedno chování a drží se blízko cíle 110 znaků.
• Důvody obsahují jednu větu a nepřesahují 180 znaků.
• Obě strany používají paralelní gramatiku, standardy důkazů, podrobnosti a vizuální váhu.
• Věcné požadavky v případě potřeby identifikují svou politiku, předpis, test nebo zdroj.
• Blok neobsahuje žádné kroky, stavy zaškrtnutí, kompromisy produktů, závažná varování, propagaci, formuláře ani vnořené komplexní prvky.
• Viditelný text říká „Zásada“ a „Chyba“; barva, pozice a ikony nejsou jedinými signály.
• Responzivní výstup udržuje každý pár pohromadě namísto skládání všech pozitivních položek před všechny negativní.
• Nadpis tématu a struktura párů zůstávají srozumitelné v prostém textu a při nedostupnosti stylů nebo skriptů.
• Strukturovaná data popisují pouze obklopující stránku a nevymýšlejí typ schema pro zásady a chyby.
• Komentáře k screenshotům zůstávají nevykreslujícími instrukcemi k zachycení, dokud neexistují skutečné assety.

FAQ

Šablona academy vykresluje pět otázek uložených v poli [[faq]] této stránky v front matter. Pokrývají úplnost párů, numerickou paritu, důvody, strukturovaná data a počet položek.