Čo robiť a čo nerobiť: Pravidlá párového usmernenia

Blok čo robiť a čo nerobiť páruje odporúčanú činnosť s chybou v rovnakom rozsahu a vysvetľuje, prečo chyba zlyháva. Jeho hodnota spočíva v kontraste: nesprávna verzia odhaľuje lákavý spôsob zlyhania, zatiaľ čo správna verzia poskytuje čitateľovi okamžitú náhradu.

Tento vykreslený príklad je produkčným modelom. Každý riadok sa venuje jednej téme na rovnakej úrovni podrobnosti. „Nerobte“ pomenúva reálnu chybu a jej dôsledok; „Robte“ poskytuje použiteľnú opravu. Rozlíšenie nesú popisy, nie farby alebo ikony.

Prečo je tento prvok dôležitý

Pravidlá sú ľahšie pochopiteľné, keď čitatelia vidia hranicu, ktorú majú rešpektovať. Samotný pozitívny pokyn môže pôsobiť abstraktne: „Používajte konkrétne dôkazy“ neodhalí, čo je príliš vágne. Samotný negatívny pokyn vytvára trenie: „Nerobte nepodložené tvrdenia“ hovorí, čomu sa vyhnúť, ale ponecháva ďalší krok nejasný. Umiestnenie oboch dohromady mení hranicu na voľbu, podľa ktorej môže čitateľ konať.

Nesprávna verzia je poučná, pretože často pripomína to, čo by zaneprázdnený človek prirodzene napísal. Ukázanie tejto takmer chyby pomáha čitateľovi rozpoznať ju vo vlastnej práci. Dôvod je rovnako dôležitý. „Nepoužívajte vágny jazyk“ vyžaduje poslušnosť; „Nepíšte „rýchly“ bez uvedenia meranej úlohy, pretože čitatelia to nevedia overiť ani porovnať“ učí princíp, ktorý sa prenáša na nové príklady.

Parita znamená, že obe strany pokrývajú ekvivalentné témy, počty, podrobnosti a redakčnú váhu. Bráni tomu, aby vedľa hromady nesúvisiacich varovaní stál vyleštený stĺpec „Robte“. Čitatelia môžu prejsť jednu dvojicu, pochopiť kontrast a pokračovať bez toho, aby si museli pamätať položku z inej časti stránky.

Strojová extrahovateľnosť je schopnosť softvéru izolovať obsah pri zachovaní jeho významu a vzťahov. Viditeľné nadpisy, štruktúra zoznamu a riadkovo zoradené dvojice umožňujú vyhľadávacím systémom a odpovedajúcim strojom získať výroky ako „Pri cenách uveďte názov plánu a dátum; vyhýbajte sa nedatovaným údajom, pretože ich rozsah je neoveriteľný.“ Ak dve strany obsahujú nesúvisiace odrážky alebo dôvod je naznačený len ikonou, extrakcia môže zachovať príkaz, ale stratiť kvalifikáciu, ktorá ho robí bezpečným.

Pred výberom tohto bloku postupujte podľa pravidiel písania prvkov . Účel má prednosť pred vzhľadom. Obsah, ktorý primárne varuje pred bezprostrednou škodou, zostáva varovaním; postupnosť zostáva zoznamom krokov; konečná sada kontrol dokončenia zostáva kontrolným zoznamom. Dva farebné stĺpce nemenia tieto účely na „čo robiť a čo nerobiť“.

Kedy to použiť

Použite tento prvok, keď čitatelia potrebujú rozlíšiť odporúčaný postup od pravdepodobnej a dôslednej chyby. Kontrast by mal znižovať nejednoznačnosť efektívnejšie ako jediný pokyn. Vhodné témy zahŕňajú redakčné štandardy, konvencie implementácie, kontroly kvality, správanie pri navrhovaní, nakladanie s údajmi a výber procesov.

Všetky tieto podmienky by mali byť splnené:

1. Každá chyba má zodpovednú náhradnú činnosť.
2. Dôvod, prečo sa chybe vyhnúť, možno uviesť v jednej krátkej vete.
3. Položky sú nezávislé usmernenia, nie kroky, ktoré treba dokončiť v poradí.
4. Obe strany môžu používať rovnaký rozsah a úroveň špecifickosti.

Časté sú prípady blízke omylu:

• Výhody a nevýhody: výhody a obmedzenia hodnotia jednu možnosť. „Čo robiť a čo nerobiť“ usmerňuje správanie čitateľa. „Zahŕňa neobmedzené projekty“ je výhoda, nie „robiť“.
• Varovanie: závažný alebo nezvratný dôsledok potrebuje priamu výraznosť a reakciu, nie sprievodný stĺpec s rovnakou váhou.
• Kontrolný zoznam: kontrolný zoznam sleduje, či je požadovaná práca dokončená. Jeho nezaškrtnutý stav nie je „nerobiť“.
• Porovnávacia tabuľka: tabuľka hodnotí niekoľko možností podľa spoločných kritérií. Nepredpisuje správne a nesprávne správanie.
• Pred a po: dva príklady môžu ukázať úpravu bez vyjadrenia opätovne použiteľného pravidla správania. Použite „čo robiť a čo nerobiť“ len vtedy, keď kontrast učí všeobecnú prax.
• Ľubovoľný domáci štýl: ak nemožno vysvetliť žiadny dôsledok pre čitateľa, systém, súlad alebo údržbu, zdokumentujte konvenciu ako pravidlo namiesto predstierania, že alternatíva je chyba.

Nepoužívajte blok na vytváranie falošného protikladu. „Robte: píšte jasne; nerobte: nepíšte nejasne“ iba parafrázuje rovnakú abstrakciu a nič neučí. Nesprávna strana musí byť dostatočne lákavá na rozpoznanie a dostatočne špecifická na diagnostikovanie.

Kam ho umiestniť

Umiestnite blok po tom, ako stránka definovala úlohu, publikum a všetky pojmy potrebné na pochopenie usmernenia. Patrí bezprostredne za vysvetlenie alebo ukážku, ktorú zhŕňa, alebo blízko konca sekcie ako praktické zhrnutie predtým, než čitateľ koná.

Presné pravidlá umiestnenia:

• Uveďte jednu tému v najbližšom nadpise. Každá dvojica musí dávať zmysel pod touto témou bez požičiavania si rozsahu zo vzdialeného odseku.
• Umiestnite blok po riadiacom princípe a pred implementačným kontrolným zoznamom alebo ďalšou akciou. Čitatelia by mali pochopiť prečo skôr, než overia dokončenie.
• V opakujúcich sa sekciách používajte rovnakú pozíciu a limit dvojíc. Presúvanie bloku na nepredvídateľné miesta sťažuje skenovanie naprieč témami.
• Uchovávajte párové zoznamy pohromade v zdrojovom poradí aj vizuálnom rozložení. Vysvetľujúca próza môže nasledovať po celom bloku, nie rozdeľovať jeho strany.

Blok nesmie stáť priamo vedľa iného dvojstĺpcového rozhodovacieho prvku, pretože susediace mriežky zatieňujú, ktoré popisy a riadky patria k sebe. Neumiestňujte medzi strany „Robte“ a „Nerobte“ svedectvo, propagačný banner, formulár ani výzvu na akciu. Nerobte z neho prvý zmysluplný obsah na stránke, ak pravidlá závisia od pojmov alebo kontextu, ktoré čitateľ ešte nedostal.

Anatómia

Popis vykreslenia

1. Nadpis témy: pomenúva ohraničenú úlohu alebo rozhodnutie zdieľané všetkými dvojicami.
2. Popis „Robte“: viditeľný text identifikujúci odporúčané správanie; ikona alebo zelené zvýraznenie je doplnkové.
3. Popis „Nerobte“: viditeľný text identifikujúci správanie, ktorému sa vyhnúť; interpunkcia používa lokalizovanú redakčnú formu.
4. Výrok o činnosti: jeden rozkazovací alebo oznamovací pokyn, ktorý pomenúva pozorovateľné správanie.
5. Dôvod: jedna veta spájajúca pokyn s dôsledkom, spôsobom zlyhania alebo riadiacim princípom.
6. Vzťah dvojice: zdrojové poradie a rozloženie zachovávajú, ktoré „Robte“ zodpovedá ktorému „Nerobte“.
7. Voliteľná poznámka o zdroji: identifikuje politiku, test, predpis alebo dôkazy, ktoré riadia faktické požiadavky.

Autor dodáva tému, dvojice a dôvody. Vykresľovač zabezpečuje rovnakú prezentáciu, responzívne skladanie, prístupné popisy a dekoratívne ikony tam, kde je to vhodné.

Príklady dizajnu

Nasledujúce varianty sú kompletnou podporovanou sadou. Menia hustotu a usporiadanie, nikdy nie zmluvu o parite alebo odôvodnení.

Štandardné párové riadky

Použite tri až sedem horizontálne zarovnaných riadkov na širokých obrazovkách. Každý riadok obsahuje jedno „Robte“ a jedno „Nerobte“ na rovnakú tému.

Skladané mobilné dvojice

Pri úzkych šírkach zachovajte každú dvojicu pohromade: „Robte“, potom „Nerobte“, potom ďalšia dvojica. Skladanie všetkých pozitívnych položiek pred všetky negatívne by skrylo korešpondenciu.

Variant vedený príkladom

Použite, keď je presný jazyk, markup alebo správanie rozhrania užitočnejšie ako abstraktný príkaz. Každá strana zobrazuje jeden krátky príklad nasledovaný jeho dôvodom. Kód zostáva vybrateľným textom.

Kompaktný variant na zhrnutie

Použite len vtedy, keď boli riadiace dôvody vysvetlené bezprostredne vyššie. Dôvod sa stále objavuje v každej položke, ale v krátkej fráze namiesto samostatného odseku.

Nevytvárajte varianty len s ikonami, karuselom, záložkami ani samostatne zbaliteľné varianty. Oddeľujú dvojicu, skrývajú jednu stranu alebo robia porovnanie závislé od interakcie.

Parametre

Zmluva modeluje dvojice, nie dva nesúvisiace zoznamy. „Zdroj“ opisuje, odkiaľ vykresľovač získava každú hodnotu.

Prvý nadpis tela sa mapuje na heading. Každá vnorená pair vlastní obe činnosti a oba dôvody. Zdrojový model nesmie ukladať všetky pozitívne položky oddelene od všetkých negatívnych, pretože by to robilo riadkovú korešpondenciu závislou od pozície v poli a ľahko porušiteľnou pri úpravách.

Syntax a príklady kódu

Všetky tri formáty zachovávajú rovnakú tému, poradie dvojíc, činnosti a dôvody. Neodvodzujú dôvod z činnosti ani automaticky nevytvárajú pozitívnu položku.

Prenosná direktíva Markdown

:::dos-and-donts
## Písanie porovnávacích tvrdení

::item{do="Uveďte presný názov plánu a dátum kontroly" dont="Neuverejňujte nedatovanú cenu"}
### Robte
Obchodné fakty sa menia, takže rozsah umožňuje čitateľom overiť a znovu použiť tvrdenie.

### Nerobte
Čitatelia nevedia určiť, ktorý plán alebo obdobie nedatovaný údaj opisuje.
::

::item{do="Porovnávajte oba produkty podľa rovnakého kritéria" dont="Neporovnávajte nesúvisiace schopnosti"}
### Robte
Spoločná miera robí rozdiel zmysluplným.

### Nerobte
Rozličné kritériá vytvárajú zdanie porovnania bez platnej voľby.
::
:::

Tento prvok prepisuje predvolené mapovanie položiek: rodičovský nadpis poskytuje heading; atribúty položiek poskytujú činnosti; prvé podnadpisy Do a Don't mapujú svoj nasledujúci text na dva dôvody.

Hugo shortcode

Žiadny produkčný Hugo shortcode v súčasnosti neimplementuje zmluvu o párových záznamoch. Kým taký neexistuje, vykresľujte sémantické HTML ako v živom príklade namiesto používania dvoch nesúvisiacich pomocníkov zoznamu. Zamýšľaný adaptér je:

{{< dos-and-donts >}}
## Písanie porovnávacích tvrdení

{{< do-dont-pair do="Uveďte presný názov plánu a dátum kontroly" dont="Neuverejňujte nedatovanú cenu" >}}
### Robte
Obchodné fakty sa menia, takže rozsah umožňuje čitateľom overiť a znovu použiť tvrdenie.
### Nerobte
Čitatelia nevedia určiť, ktorý plán alebo obdobie nedatovaný údaj opisuje.
{{< /do-dont-pair >}}
{{< /dos-and-donts >}}

Budúci vykresľovač musí produkovať jednu označenú oblasť so zoznamom párových záznamov. Nesmie vytvárať dve polia a spájať ich podľa indexu po vykreslení.

WordPress blok alebo shortcode

[dos_and_donts heading="Písanie porovnávacích tvrdení" variant="standard"]
[pair]
[do action="Uveďte presný názov plánu a dátum kontroly"]Obchodné fakty sa menia, takže rozsah umožňuje čitateľom overiť a znovu použiť tvrdenie.[/do]
[dont action="Neuverejňujte nedatovanú cenu"]Čitatelia nevedia určiť, ktorý plán alebo obdobie nedatovaný údaj opisuje.[/dont]
[/pair]
[pair]
[do action="Porovnávajte oba produkty podľa rovnakého kritéria"]Spoločná miera robí rozdiel zmysluplným.[/do]
[dont action="Neporovnávajte nesúvisiace schopnosti"]Rozličné kritériá vytvárajú zdanie porovnania bez platnej voľby.[/dont]
[/pair]
[/dos_and_donts]

Vlastný WordPress blok by mal upravovať každú dvojicu ako jeden záznam a brániť publikovaniu, keď chýba činnosť alebo dôvod.

Príklady

Dobrý: ekvivalentný, realizovateľný a odôvodnený

Dvojice zdieľajú tému v každom riadku: rozsah plánu, časové okno a stav dôkazov. Obe činnosti sú dostatočne špecifické na posúdenie v koncepte a každý dôvod vysvetľuje, čo sa môže pokaziť. Čitateľ môže princíp aplikovať, aj keď sa presná cena, produkt alebo obdobie mení.

Zlý: dve hromady príkazov

| Zjednodušte to | Vyhýbajte sa príliš mnohým odkazom | | Skontrolujte fakty | — |

Toto zlyháva, pretože stĺpce sú nesúvisiace a nerovné. „Buďte presní“ nemá pozorovateľnú podmienku dokončenia, zatiaľ čo „Nikdy nepoužívajte žargón“ zakazuje jazyk bez rozlíšenia potrebných a nevysvetlených termínov. Žiadna z negatívnych položiek neuvádza dôsledok a prázdna bunka odhaľuje, že autor vytvoril dva zoznamy, nie štyri dvojice.

Opravte blok výberom jednej témy a následným písaním ekvivalentných riadkov. Pre terminológiu by dvojica mohla byť: „Definujte potrebný odborný termín pri prvom použití, pretože definícia umožňuje nováčikom sledovať argument“ a „Nenahrádzajte presný termín vágou každodennou frázou, pretože substitúcia môže zmeniť význam.“ Oprava učí úsudok namiesto vynucovania slogana.

Schema markup a prístupnosť

Schema.org neposkytuje všeobecný typ DoAndDont. Uchovávajte viditeľný blok v rámci ohraničujúceho Article, TechArticle, HowTo alebo iných štruktúrovaných údajov na úrovni stránky, ak stránka skutočne spĺňa podmienky. Neprevádzajte pozitívne položky na záznamy HowToStep, pokiaľ netvoria usporiadaný postup, a neuverejňujte dvojice ako FAQPage len preto, že obsahujú krátke vysvetlenia.

Používajte natívne nadpisy a zoznamy. Jedna vonkajšia sekcia dostáva svoj prístupný názov z nadpisu témy. Každá dvojica by mala byť jednou položkou zoznamu alebo zoskupeným záznamom obsahujúcim viditeľný popis „Robte“ a viditeľný popis „Nerobte“. Zachovajte každú dvojicu v zdrojovom poradí, aby používateľ čítačky obrazovky narazil na odporúčanie a jeho zodpovedajúcu chybu spoločne.

Farby a ikony sú doplnkové. Zelená nemôže byť jediným signálom pre „Robte“ a krížik nemôže byť jediným signálom pre „Nerobte“. Dekoratívne ikony dostávajú prázdny alternatívny text alebo sú skryté pred asistenčnými technológiami. Nerobte statický blok zamerateľný. Ak je horizontálny prebytok nevyhnutný pre príkladovú tabuľku, obsahujte a označte oblasť posúvania; produkčný komponent by mal namiesto toho skladať dvojice.

Skratka „Don’t“ je prijateľná ako viditeľný redakčný text. Kódové polia používajú ASCII-bezpečné dont tam, kde by apostrofy komplikovali názvy atribútov. Vykresľovače lokalizujú popisy bez zmeny uložených činností alebo dôvodov.

Pravidlá písania

Napíšte dôvod pred finalizáciou príkazu. To núti autora identifikovať dôsledok pre čitateľa, systém, bezpečnosť, súlad alebo údržbu. Ak nemožno napísať obhájiteľný dôvod, zákaz môže byť skôr preferenciou než usmernením.

Použite tri až sedem dvojíc. Každá činnosť by mala vyjadrovať jedno pozorovateľné správanie v 110 znakoch alebo menej tam, kde je to praktické. Každej strane dajte jednu dôvodovú vetu najviac o 180 znakoch. Limity udržujú obe strany prehľadné; dlhšie kvalifikácie patria do okolitej prózy.

Udržujte paritu v piatich dimenziách:

• Téma: obe činnosti sa týkajú rovnakého rozhodnutia alebo artefaktu.
• Úroveň: presné markupové pravidlo nemožno párovať so širokou zásadou ako „píšte dobre“.
• Gramatika: používajte paralelné rozkazovacie alebo paralelné oznamovacie vety.
• Dôkazy: na obe strany aplikujte rovnakú faktickú a zdrojovú prahovú hodnotu.
• Vizuálna váha: ani jedna strana nedostáva viac miesta, dôrazu, podrobností alebo predvolenej viditeľnosti.

Používajte priamy, neutrálny jazyk. Uprednostnite „Neuverejňujte neoverenú cenu“ pred hanlivým jazykom ako „Len nedbalí autori zabúdajú overiť ceny.“ Vyhýbajte sa sarkazmu, strachu a absolútnym výrazom, pokiaľ pravidlo nie je skutočne absolútne a jeho rozsah je uvedený.

Nikdy nedávajte do prvku tieto veci:

• Nesúvisiace tipy pridané na vyplnenie jednej strany alebo vynútenie numerickej symetrie.
• Zákaz bez dôsledku, princípu alebo náhradnej činnosti.
• Usporiadané postupy, zaškrtávacie políčka, hodnotenia, verdikty ani výhody a obmedzenia produktov.
• Bezpečnostne kritické varovania, právne vyhlásenia, núdzové pokyny ani oznámenia o nezvratných krokoch.
• Svedectvá, dlhé citácie, médiá, formuláre, výzvy na akciu, propagačné tlačidlá ani kupónové kódy.
• Vnorené accordiony, záložky, karusely, porovnávacie tabuľky ani ďalší blok „čo robiť a čo nerobiť“.
• Tvrdenia o ľuďoch alebo skupinách rámcované ako morálne zlyhanie, nie pozorovateľné správanie.

Keď požiadavka pochádza z politiky, predpisu, testu alebo externého štandardu, pridajte blízku poznámku o zdroji. Priraďte pravidlo dostatočne presne, aby ho redaktor mohol znova skontrolovať; nenechávajte blok niesť dlhý citačný aparát.

Typy príspevkov, ktoré ho používajú

Pole postTypes v frontmatter riadi túto maticu použitia. Zahrnutie sprístupňuje prvok za uvedenej podmienky; nerobí blok povinným na každej stránke tohto typu.

Kontrolný zoznam QA

• Blok má jednu ohraničenú tému, ktorá je jasná z jeho najbližšieho nadpisu.
• Riadiaci princíp sa objavuje pred blokom, takže dvojice pravidlo posilňujú, nie vymýšľajú.
• Existuje tri až sedem kompletných dvojíc a presne rovnaký počet činností „Robte“ a „Nerobte“.
• Každá dvojica sa týka rovnakej témy, publika, rozsahu a úrovne špecifickosti.
• Každé „Nerobte“ pomenúva reálnu chybu a vysvetľuje jej dôsledok alebo spôsob zlyhania.
• Každé „Robte“ poskytuje realizovateľnú náhradu a vysvetľuje, prečo funguje.
• Žiadna položka len nepopiera svojho partnera, neopakuje slogan ani nepoužíva kruhové vyjadrenie.
• Činnosti obsahujú jedno správanie a držia sa blízko cieľa 110 znakov.
• Dôvody obsahujú jednu vetu a zostávajú do 180 znakov.
• Obe strany používajú paralelnú gramatiku, štandardy dôkazov, podrobnosť a vizuálnu váhu.
• Faktické požiadavky v prípade potreby identifikujú svoju politiku, predpis, test alebo zdroj.
• Blok neobsahuje žiadne kroky, stavy zaškrtnutia, kompromisy produktov, závažné varovania, propagáciu, formuláre ani vnorené zložité prvky.
• Viditeľný text hovorí „Robte“ a „Nerobte“; farba, pozícia a ikony nie sú jedinými signálmi.
• Responzívny výstup udržuje každú dvojicu pohromade namiesto skladania všetkých pozitívnych položiek pred všetky negatívne.
• Nadpis témy a štruktúra dvojíc zostávajú zrozumiteľné v prostom texte a keď nie sú k dispozícii štýly alebo skripty.
• Štruktúrované údaje opisujú len ohraničujúcu stránku a nevymýšľajú typ schema pre „čo robiť a čo nerobiť“.
• Komentáre k screenshotom zostávajú nezobrazovacie inštrukcie na zachytenie, kým neexistujú skutočné assety.

FAQ

Šablóna academy vykresľuje päť otázok uložených v [[faq]] frontmatter tejto stránky. Týkajú sa úplnosti dvojíc, numerickej parity, dôvodov, štruktúrovaných údajov a počtu položiek.