Gör och gör inte: Parade vägledningsregler

Ett gör-och-gör-inte-block parar ihop en rekommenderad handling med ett misstag inom samma omfattning och förklarar varför misstaget misslyckas. Dess värde kommer från kontrasten: den felaktiga versionen exponerar ett frestande feltillstånd, medan den rätta versionen ger läsaren en omedelbar ersättning.

Detta renderade exempel är produktionsmodellen. Varje rad behandlar ett ämne på samma detaljnivå. “Gör inte” namnger ett realistiskt fel och dess konsekvens; “Gör” tillhandahåller en användbar korrigering. Etiketter, inte färg eller ikoner, bär åtskillnaden.

Varför detta element är viktigt

Regler är lättare att förstå när läsare kan se gränsen de ska respektera. En positiv instruktion ensam kan kännas abstrakt: “Använd specifika bevis” avslöjar inte vad som räknas som alltför vagt. En negativ instruktion ensam skapar friktion: “Gör inte ogrundade påståenden” säger vad man ska undvika men lämnar nästa steg oklart. Att placera de två tillsammans förvandlar en gräns till ett val läsaren kan agera på.

Den felaktiga versionen är lärorik eftersom den ofta liknar vad en stressad person naturligt skulle skriva. Att visa den närliggande missen hjälper läsaren att känna igen den i sitt eget arbete. Anledningen är lika viktig. “Använd inte vagt språk” kräver lydnad; “Skriv inte ‘snabb’ utan att nämna den uppmätta uppgiften, eftersom läsare inte kan verifiera eller jämföra det” lär ut en princip som överförs till nya exempel.

Paritet innebär att båda sidor täcker likvärdiga ämnen, antal, detaljer och redaktionell vikt. Det förhindrar att en polerad “Gör”-kolumn sitter bredvid en hög med orelaterade varningar. Läsare kan skanna ett par, förstå kontrasten och fortsätta utan att behöva minnas en punkt från någon annanstans på sidan.

Maskinextraherbarhet är förmågan hos programvara att isolera innehåll samtidigt som dess betydelse och relationer bevaras. Synliga rubriker, liststruktur och radjusterade par låter söksystem och svarsmotorer återvinna påståenden som “För priser, ange plan och datum; undvik odaterade siffror eftersom deras omfattning inte är verifierbar.” Om de två sidorna innehåller orelaterade punkter eller anledningen bara antyds av en ikon, kan extraktion bevara kommandot samtidigt som kvalifikationen som gör det säkert går förlorad.

Följ element writing rules innan du väljer detta block. Syfte har företräde framför utseende. Innehåll som främst varnar för omedelbar skada förblir en varning; en sekvens förblir en steglista; en ändlig uppsättning slutförandekontroller förblir en checklista. Två färgade kolumner gör inte om dessa syften till gör-och-gör-inte-block.

När det ska användas

Använd detta element när läsare behöver skilja en rekommenderad praxis från ett troligt, konsekvensrikt misstag. Kontrasten bör minska tvetydighet mer effektivt än en enskild instruktion. Lämpliga ämnen inkluderar redaktionella standarder, implementationskonventioner, kvalitetskontroller, designbeteende, datahantering och processval.

Alla dessa villkor bör vara uppfyllda:

1. Varje misstag har en ansvarsfull ersättningshandling.
2. Anledningen till att undvika misstaget kan anges i en kort mening.
3. Punkterna är oberoende vägledning, inte steg som måste utföras i ordning.
4. Båda sidor kan använda samma omfattning och detaljnivå.

Närliggande fall är vanliga:

• För- och nackdelar: fördelar och begränsningar utvärderar ett alternativ. Gör och gör inte instruerar läsarens beteende. “Innehåller obegränsade projekt” är en fördel, inte ett gör.
• Varning: en allvarlig eller irreversibel konsekvens behöver direkt framträdande plats och en åtgärd, inte en kolumn med lika vikt som en följeslagare.
• Checklista: en checklista spårar om nödvändigt arbete är slutfört. Dess icke-ifyllda tillstånd är inte ett “Gör inte.”
• Jämförelsetabell: en tabell utvärderar flera alternativ mot gemensamma kriterier. Den föreskriver inte korrekt och felaktigt beteende.
• Före och efter: två exempel kan visa en redigering utan att uttrycka en återanvändbar beteenderegel. Använd gör och gör inte endast när kontrasten lär ut en allmän praxis.
• Godtycklig husstil: om ingen konsekvens för läsare, system, efterlevnad eller underhåll kan förklaras, dokumentera konventionen som en regel istället för att låtsas att alternativet är ett misstag.

Använd inte blocket för att skapa opposition. “Skriv tydligt; skriv inte otydligt” omformulerar samma abstraction och lär ut ingenting. Den felaktiga sidan måste vara frestande nog att känna igen och specifik nog att diagnostisera.

Var det ska placeras

Placera blocket efter att sidan har definierat uppgiften, målgruppen och eventuella termer som behövs för att förstå vägledningen. Det hör hemma omedelbart efter förklaringen eller demonstrationen den sammanfattar, eller i slutet av ett avsnitt som en praktisk genomgång innan läsaren agerar.

Exakta placeringsregler:

• Introducera ett ämne i närmaste rubrik. Varje par måste vara meningsfullt under det ämnet utan att låna omfattning från ett avlägset stycke.
• Placera blocket efter den styrande principen och före en implementationschecklista eller nästa åtgärd. Läsare bör förstå varför innan de verifierar slutförande.
• I upprepade avsnitt, använd samma position och pargränser. Att flytta blocket oförutsägbart gör det svårare att skanna över ämnen.
• Håll de parade listorna tillsammans i källordning och visuell layout. Förklarande prosa kan följa hela blocket, inte dela upp dess sidor.

Det får inte placeras direkt bredvid ett annat tvåkolumnigt beslutselement, eftersom intilliggande rutnät gör oklart vilka etiketter och rader som hör ihop. Placera inte ett vittnesbörd, reklambanner, formulär eller uppmaning till handling mellan “Gör”- och “Gör inte”-sidorna. Gör det inte till det första meningsfulla innehållet på en sida när reglerna beror på termer eller sammanhang läsaren ännu inte fått.

Anatomi

Renderad förklaring

1. Ämnesrubrik: namnger den avgränsade uppgiften eller beslutet som delas av varje par.
2. Gör-etikett: synlig text som identifierar rekommenderat beteende; en ikon eller grön behandling är kompletterande.
3. Gör inte-etikett: synlig text som identifierar beteende att undvika; skiljetecken använder den lokaliserade redaktionella formen.
4. Handlingspåstående: en imperativ eller deklarativ instruktion som namnger observerbart beteende.
5. Anledning: en mening som kopplar instruktionen till en konsekvens, felorsak eller styrande princip.
6. Parrelation: källordning och layout bevarar vilket “Gör” som svarar på vilket “Gör inte.”
7. Valfri källnot: identifierar policyn, testet, regeln eller beviset som styr faktiska krav.

Författaren tillhandahåller ämnet, paren och anledningarna. Renderingen tillhandahåller lika presentation, responsiv stapling, tillgängliga etiketter och dekorativa ikoner där så är lämpligt.

Designexempel

Följande varianter är den fullständiga uppsättningen som stöds. De ändrar täthet och arrangemang, aldrig paritets- eller resonemangsavtalet.

Standardparade rader

Använd tre till sju horisontellt justerade rader på breda skärmar. Varje rad innehåller ett “Gör” och ett “Gör inte” om samma ämne.

Staplade mobilpar

Vid smala bredder, håll varje par tillsammans: “Gör,” sedan “Gör inte,” sedan nästa par. Att stapla alla positiva punkter före alla negativa punkter skulle dölja överensstämmelsen.

Exempelledd variant

Använd när exakt språk, markup eller gränssnittsbeteende är mer användbart än ett abstrakt kommando. Varje sida visar ett kort exempel följt av dess anledning. Kod förblir valbar text.

Kompakt granskningsvariant

Använd endast när de styrande anledningarna redan har förklarats omedelbart ovanför. Anledningen visas fortfarande i varje punkt, men i en kort fras snarare än ett separat stycke.

Skapa inte varianter med endast ikoner, karuseller, flikar eller oberoende hopfällbara element. De separerar paret, döljer en sida eller gör jämförelse beroende av interaktion.

Parametrar

Avtalet modellerar par snarare än två orelaterade listor. “Källa” beskriver var renderingen hämtar varje värde.

Den första brödtextrubriken mappar till heading. Varje nästlat pair äger båda handlingarna och båda anledningarna. Källmodellen får inte lagra alla positiva punkter separat från alla negativa punkter, eftersom det gör radöverensstämmelse beroende av arrayposition och lätt att bryta vid redigering.

Syntax och kodexempel

Alla tre format bevarar samma ämne, parordning, handlingar och anledningar. De härleder inte en anledning från handlingen eller skapar automatiskt en positiv punkt.

Portabel Markdown-direktiv

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

Detta element åsidosätter standardobjektmappningen: den överordnade rubriken levererar heading; objektsattributen levererar handlingarna; de första underrubrikerna Do och Don't mappar sin efterföljande text till de två anledningarna.

Hugo-shortcode

Ingen produktions-Hugo-shortcode implementerar för närvarande det parade postavtalet. Tills en sådan finns, rendera semantisk HTML som live-exemplet istället för att använda två orelaterade listhjälpmedel. Den avsedda adaptern är:

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

Den framtida renderingen måste producera en märkt region med en lista över parade poster. Den får inte skapa två arrayer och zippa dem efter index vid rendering.

WordPress-block eller 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]

Ett anpassat WordPress-block bör redigera varje par som en post och förhindra publicering när en handling eller anledning saknas.

Exempel

Bra: likvärdiga, handlingsbara och motiverade

Paren delar ett ämne i varje rad: planomfattning, tidsfönster och bevisstatus. Båda handlingarna är tillräckligt specifika för att granska i ett utkast, och varje anledning förklarar vad som kan gå fel. En läsare kan tillämpa principen även när det exakta priset, produkten eller perioden ändras.

Dåligt: två högar med kommandon

Detta misslyckas eftersom kolumnerna är orelaterade och ojämlika. “Var korrekt” har inget observerbart slutförandevillkor, medan “Använd aldrig jargong” förbjuder språk utan att skilja nödvändiga termer från oförklarade termer. Ingen av de negativa punkterna anger en konsekvens, och den tomma cellen avslöjar att författaren skapade två listor snarare än fyra par.

Reparera blocket genom att välja ett ämne, skriv sedan likvärdiga rader. För terminologi skulle paret kunna vara: “Definiera en nödvändig fackterm vid första användningen, eftersom definitionen låter nykomlingar följa argumentet” och “Ersätt inte en precis term med ett vagt vardagsuttryck, eftersom substitutionen kan ändra betydelsen.” Korrigeringen lär ut omdöme istället för att tvinga fram en slogan.

Schema-markup och tillgänglighet

Schema.org tillhandahåller ingen allmän DoAndDont-typ. Behåll det synliga blocket inom den omgivande Article, TechArticle, HowTo eller annan sidnivåstrukturerad data när den sidan verkligen kvalificerar. Konvertera inte de positiva punkterna till HowToStep-poster om de inte utgör en ordnad procedur, och publicera inte paren som FAQPage enbart för att de innehåller korta förklaringar.

Använd naturliga rubriker och listor. En yttre sektion får sitt tillgängliga namn från ämnesrubriken. Varje par bör vara en listpunkt eller grupperad post som innehåller en synlig “Gör”-etikett och en synlig “Gör inte”-etikett. Bevara varje par i källordning så att en skärmläsaranvändare möter rekommendationen och dess matchande misstag tillsammans.

Färg och ikoner är kompletterande. Grönt kan inte vara den enda signalen för “Gör,” och ett kryss kan inte vara den enda signalen för “Gör inte.” Dekorativa ikoner får tom alternativtext eller döljs för hjälpmedelsteknik. Gör inte ett statiskt block fokuserbart. Om horisontellt överflöde är oundvikligt för en exempeltabell, inneslut och märk rullningsområdet; produktionskomponenten bör stapla par istället.

Förkortningen “Don’t” är acceptabel som synlig redaktionell text. Kodfält använder ASCII-säkra dont där apostrofer skulle komplicera attributnamn. Renderingar lokaliserar etiketterna utan att ändra de lagrade handlingarna eller anledningarna.

Skrivregler

Skriv anledningen innan du slutför kommandot. Detta tvingar författaren att identifiera konsekvensen för läsare, system, säkerhet, efterlevnad eller underhåll. Om en försvarbar anledning inte kan skrivas, kan förbudet vara en preferens snarare än vägledning.

Använd tre till sju par. Varje handling bör uttrycka ett observerbart beteende på 110 tecken eller färre där det är praktiskt. Ge varje sida en anledningsmening på högst 180 tecken. Gränserna håller de två sidorna skanningsbara; längre kvalifikationer hör hemma i omgivande prosa.

Bibehåll paritet över fem dimensioner:

• Ämne: båda handlingarna behandlar samma beslut eller artefakt.
• Nivå: en exakt markupregel kan inte paras med en bred maxim som “skriv väl.”
• Grammatik: använd parallella imperativ eller parallella deklarativa påståenden.
• Bevis: tillämpa samma faktiska och källhänvisande tröskel på båda sidor.
• Visuell vikt: ingen sida får mer utrymme, betoning, detalj eller standard synlighet.

Använd direkt, neutralt språk. Föredra “Publicera inte ett overifierat pris” framför skambeläggande språk som “Endast slarviga skribenter glömmer att verifiera priser.” Undvik sarkasm, rädsla och absoluta termer om inte regeln är verkligt absolut och dess omfattning anges.

Placera aldrig dessa inuti elementet:

• Orelaterade tips som lagts till för att fylla en sida eller tvinga fram numerisk symmetri.
• Ett förbud utan konsekvens, princip eller ersättningshandling.
• Ordnade procedurer, kryssrutor, betyg, domar eller produktfördelar och begränsningar.
• Säkerhetskritiska varningar, juridiska ansvarsfriskrivningar, akuta instruktioner eller meddelanden om irreversibla åtgärder.
• Vittnesbörd, långa citat, media, formulär, uppmaningar till handling, reklamknappar eller kupongkoder.
• Nästlade accordions, flikar, karuseller, jämförelsetabeller eller ett annat gör-och-gör-inte-block.
• Påståenden om personer eller grupper som framställs som moraliskt misslyckande snarare än observerbart beteende.

När ett krav kommer från en policy, reglering, test eller extern standard, lägg till en källnot i närheten. Attribuera regeln tillräckligt precist för att en redaktör ska kunna kontrollera den igen; låt inte blocket bära en lång citationsapparat.

Inläggstyper som använder det

postTypes-frontmatter-arrayen driver denna användningsmatris. Inkludering gör elementet tillgängligt under angivet villkor; det gör inte blocket obligatoriskt på varje sida av den typen.

QA-checklista

• Blocket har ett avgränsat ämne som framgår av dess närmaste rubrik.
• Den styrande principen visas före blocket, så paren förstärker snarare än uppfinner regeln.
• Det finns tre till sju fullständiga par och exakt samma antal “Gör” och “Gör inte”-handlingar.
• Varje par behandlar samma ämne, målgrupp, omfattning och detaljnivå.
• Varje “Gör inte” namnger ett realistiskt misstag och förklarar dess konsekvens eller felorsak.
• Varje “Gör” tillhandahåller en handlingsbar ersättning och förklarar varför den fungerar.
• Ingen punkt bara negerar sin partner, upprepar en slogan eller använder cirkulär formulering.
• Handlingar innehåller ett beteende och håller sig nära 110-teckensmålet.
• Anledningar innehåller en mening och håller sig inom 180 tecken.
• Båda sidor använder parallell grammatik, bevisstandarder, detalj och visuell vikt.
• Faktiska krav identifierar sin policy, reglering, test eller källa där nödvändigt.
• Blocket innehåller inga steg, kontrolltillstånd, produktavvägningar, allvarliga varningar, reklam, formulär eller nästlade komplexa element.
• Synlig text säger “Gör” och “Gör inte”; färg, position och ikoner är inte de enda signalerna.
• Responsiv utdata håller varje par tillsammans istället för att stapla alla positiva punkter före alla negativa punkter.
• Ämnesrubriken och parstrukturen förblir begripliga i vanlig text och när stilar eller skript inte är tillgängliga.
• Strukturerad data beskriver endast den omgivande sidan och uppfinner inte en gör-och-gör-inte-schematyp.
• Skärmdumpskommentarer förblir icke-renderande inspelningsinstruktioner tills verkliga tillgångar finns.

FAQ

Academy-mallen renderar de fem frågor som lagras i denna sidas [[faq]]-frontmatter. De täcker parfullständighet, numerisk paritet, anledningar, strukturerad data och antal punkter.