Gjør og ikke gjør: Parede veiledningsregler

En gjør-og-ikke-gjør-blokk parer en anbefalt handling med en feil av samme omfang og forklarer hvorfor feilen mislykkes. Verdien kommer fra kontrast: den gale versjonen avslører en fristende feilmodus, mens den riktige versjonen gir leseren en umiddelbar erstatning.

Dette gjengitte eksemplet er produksjonsmodellen. Hver rad behandler ett emne på samme detaljnivå. «Ikke gjør» navngir en realistisk feil og dens konsekvens; «Gjør» gir en brukbar korrigering. Etiketter, ikke farge eller ikoner, bærer skillet.

Hvorfor dette elementet er viktig

Regler er lettere å forstå når lesere kan se grensen de skal respektere. En positiv instruksjon alene kan føles abstrakt: «Bruk spesifikke bevis» avslører ikke hva som regnes som for vagt. En negativ instruksjon alene skaper friksjon: «Ikke kom med ubegrunnede påstander» sier hva man skal unngå, men etterlater neste steg uklart. Å sette de to sammen gjør en grense om til et valg leseren kan handle på.

Den gale versjonen er lærerik fordi den ofte ligner på hva en travel person naturlig ville skrevet. Å vise den nesten-feilen hjelper leseren å gjenkjenne den i eget arbeid. Grunnen er like viktig. «Ikke bruk vagt språk» krever lydighet; «Ikke skriv ‘raskt’ uten å nevne den målte oppgaven, fordi lesere ikke kan verifisere eller sammenligne det» lærer et prinsipp som overføres til nye eksempler.

Paritet betyr at begge sider dekker likeverdige emner, antall, detaljer og redaksjonell vekt. Det hindrer en polert «Gjør»-kolonne fra å sitte ved siden av en haug med urelaterte advarsler. Lesere kan skanne ett par, forstå kontrasten, og fortsette uten å huske et element fra et annet sted på siden.

Maskinekstraherbarhet er evnen programvare har til å isolere innhold samtidig som betydning og relasjoner bevares. Synlige overskrifter, listestruktur og radjusterte par lar søkesystemer og svarmotorer gjenfinne utsagn som «For priser, oppgi plan og dato; unngå udaterte tall fordi omfanget ikke kan verifiseres.» Hvis de to sidene inneholder urelaterte punkter eller grunnen bare antydes med et ikon, kan maskinell lesing bevare kommandoen mens den mister kvalifikasjonen som gjør den trygg.

Følg skrivereglene for elementer før du velger denne blokken. Formål går foran utseende. Innhold som primært advarer om umiddelbar skade forblir en advarsel; en sekvens forblir en stegliste; et avgrenset sett med fullføringskontroller forblir en sjekkliste. To fargede kolonner gjør ikke disse formålene om til gjør og ikke gjør.

Når du skal bruke det

Bruk dette elementet når lesere trenger å skille mellom en anbefalt praksis og en plausibel, konsekvensrik feil. Kontrasten bør redusere tvetydighet mer effektivt enn én enkelt instruksjon. Egnede emner inkluderer redaksjonelle standarder, implementeringskonvensjoner, kvalitetskontroller, designatferd, datahåndtering og prosessvalg.

Alle disse betingelsene bør være oppfylt:

1. Hver feil har en ansvarlig erstatningshandling.
2. Grunnen til å unngå feilen kan angis i én kort setning.
3. Elementene er uavhengig veiledning, ikke steg som må fullføres i rekkefølge.
4. Begge sider kan bruke samme omfang og presisjonsnivå.

Nestenlike tilfeller er vanlige:

• Fordeler og ulemper: fordeler og begrensninger vurderer ett alternativ. Gjør og ikke gjør instruerer leserens atferd. «Inkluderer ubegrensede prosjekter» er en fordel, ikke et gjør.
• Advarsel: en alvorlig eller irreversibel konsekvens trenger direkte fremtredende plass og en respons, ikke en likeverdig følgekolonne.
• Sjekkliste: en sjekkliste sporer om nødvendig arbeid er fullført. Dens ukryssede tilstand er ikke et «Ikke gjør».
• Sammenligningstabell: en tabell vurderer flere alternativer mot felles kriterier. Den foreskriver ikke korrekt og ukorrekt atferd.
• Før og etter: to eksempler kan vise en redigering uten å uttrykke en gjenbrukbar atferdsregel. Bruk gjør og ikke gjør bare når kontrasten lærer en generell praksis.
• Vilkårlig husstil: hvis ingen leser-, system-, etterlevelses- eller vedlikeholdskonsekvens kan forklares, dokumenter konvensjonen som en regel i stedet for å late som alternativet er en feil.

Ikke bruk blokken til å fabrikkere motsetninger. «Gjør: skriv tydelig; ikke gjør: skriv utydelig» gjentar den samme abstraksjonen og lærer ingenting. Den gale siden må være fristende nok til å gjenkjennes og spesifikk nok til å diagnostiseres.

Hvor du skal plassere den

Plasser blokken etter at siden har definert oppgaven, målgruppen og eventuelle begreper som trengs for å forstå veiledningen. Den hører hjemme umiddelbart etter forklaringen eller demonstrasjonen den oppsummerer, eller nær slutten av en seksjon som en praktisk gjennomgang før leseren handler.

Eksakte plasseringsregler:

• Innfør ett emne i nærmeste overskrift. Hvert par må gi mening under det emnet uten å låne omfang fra et fjernt avsnitt.
• Sett blokken etter det styrende prinsippet og før en implementeringssjekkliste eller neste handling. Lesere bør forstå hvorfor før de verifiserer fullføring.
• I gjentatte seksjoner, bruk samme posisjon og parbegrensninger. Å flytte blokken uforutsigbart gjør det vanskeligere å skanne på tvers av emner.
• Hold de parede listene sammen i kildekode og visuell layout. Forklarende prosa kan følge den komplette blokken, ikke splitte sidene.

Den kan ikke plasseres rett ved siden av et annet to-kolonne beslutningselement, fordi tilstøtende rutenettoppsett gjør det uklart hvilke etiketter og rader som hører sammen. Ikke plasser et vitnesbyrd, reklamebanner, skjema eller handlingsfremmende uttrykk mellom «Gjør»- og «Ikke gjør»-sidene. Ikke gjør den til det første meningsfulle innholdet på en side når reglene avhenger av begreper eller kontekst leseren ennå ikke har fått.

Anatomi

Gjengitt forklaring

1. Emneoverskrift: navngir den avgrensede oppgaven eller beslutningen som deles av hvert par.
2. Gjør-etikett: synlig tekst som identifiserer anbefalt atferd; et ikon eller grønn utførelse er tillegg.
3. Ikke gjør-etikett: synlig tekst som identifiserer atferd som skal unngås; tegnsetting bruker den lokaliserte redaksjonelle formen.
4. Handlingsutsagn: én imperativ eller deklarativ instruksjon som navngir observerbar atferd.
5. Grunner: én setning som knytter instruksjonen til en konsekvens, feilmodus eller styrende prinsipp.
6. Par-relasjon: kildekodeorden og layout bevarer hvilket «Gjør» som svarer til hvilket «Ikke gjør».
7. Valgfri kildenotat: identifiserer policyen, testen, reguleringen eller bevisene som styrer faktakrav.

Forfatteren leverer emnet, parene og grunnene. Gjengiveren sørger for lik presentasjon, responsiv stabling, tilgjengelige etiketter og dekorative ikoner der det er hensiktsmessig.

Designeksempler

Følgende varianter er det komplette støttede settet. De endrer tetthet og arrangement, aldri pariteten eller begrunnelseskontrakten.

Standard parede rader

Bruk tre til syv horisontalt justerte rader på brede skjermer. Hver rad inneholder ett «Gjør» og ett «Ikke gjør» om samme emne.

Stablede mobilpar

Ved smale bredder, hold hvert par sammen: «Gjør», så «Ikke gjør», så neste par. Å stable alle positive elementer før alle negative elementer ville skjule korrespondansen.

Eksempel-ledet variant

Bruk når eksakt språk, markering eller grensesnittatferd er mer nyttig enn en abstrakt kommando. Hver side viser ett kort eksempel etterfulgt av sin grunn. Kode forblir valgbar tekst.

Kompakt gjennomgangsvariant

Bruk bare når de styrende grunnene allerede er forklart rett over. Grunnen vises fortsatt i hvert element, men i en kort setning i stedet for et eget avsnitt.

Ikke lag varianter med bare ikoner, karusell, faner eller uavhengig sammenleggbare elementer. De skiller paret, skjuler én side, eller gjør sammenligning avhengig av interaksjon.

Parametere

Kontrakten modellerer par snarere enn to urelaterte lister. «Kilde» beskriver hvor gjengiveren henter hver verdi.

Den første brødtekstoverskriften kartlegges til heading. Hvert nestet pair eier både handlinger og begge grunner. Kildemodellen må ikke lagre alle positive elementer separat fra alle negative elementer, fordi det gjør radkorrespondanse avhengig av matriseposisjon og lett å ødelegge under redigering.

Syntaks og kodeeksempler

Alle tre formatene bevarer samme emne, parrekkefølge, handlinger og grunner. De utleder ikke en grunn fra handlingen eller oppretter automatisk et positivt element.

Bærbar Markdown-direktiv

:::dos-and-donts
## Skrive sammenligningspåstander

::item{do="Oppgi nøyaktig plan og dato kontrollert" dont="Ikke publiser en udatert pris"}
### Gjør
Kommersielle fakta endrer seg, så avgrensning lar lesere verifisere og gjenbruke påstanden.

### Ikke gjør
Lesere kan ikke se hvilken plan eller periode en udatert pris beskriver.
::

::item{do="Sammenlign begge produktene på samme kriterium" dont="Ikke sammenlign urelaterte egenskaper"}
### Gjør
Et felles mål gjør forskjellen meningsfull.

### Ikke gjør
Ulike kriterier skaper et inntrykk av sammenligning uten et gyldig valg.
::
:::

Dette elementet overstyrer standard elementkartlegging: den overordnede overskriften leverer heading; elementattributter leverer handlingene; de første Gjør- og Ikke gjør-underoverskriftene kartlegger sin påfølgende tekst til de to grunnene.

Hugo-shortkode

Ingen produksjons-Hugo-shortkode implementerer for øyeblikket parepost-kontrakten. Inntil en eksisterer, gjengi semantisk HTML som live-eksemplet i stedet for å bruke to urelaterte liste-hjelpere. Den tiltenkte adapteren er:

{{< dos-and-donts >}}
## Skrive sammenligningspåstander

{{< do-dont-pair do="Oppgi nøyaktig plan og dato kontrollert" dont="Ikke publiser en udatert pris" >}}
### Gjør
Kommersielle fakta endrer seg, så avgrensning lar lesere verifisere og gjenbruke påstanden.
### Ikke gjør
Lesere kan ikke se hvilken plan eller periode en udatert pris beskriver.
{{< /do-dont-pair >}}
{{< /dos-and-donts >}}

Den fremtidige gjengiveren må produsere én merket region med en liste over parede poster. Den må ikke opprette to matriser og zippe dem etter indeks etter gjengivelse.

WordPress-blokk eller shortkode

[dos_and_donts heading="Skrive sammenligningspåstander" variant="standard"]
[pair]
[do action="Oppgi nøyaktig plan og dato kontrollert"]Kommersielle fakta endrer seg, så avgrensning lar lesere verifisere og gjenbruke påstanden.[/do]
[dont action="Ikke publiser en udatert pris"]Lesere kan ikke se hvilken plan eller periode en udatert pris beskriver.[/dont]
[/pair]
[pair]
[do action="Sammenlign begge produktene på samme kriterium"]Et felles mål gjør forskjellen meningsfull.[/do]
[dont action="Ikke sammenlign urelaterte egenskaper"]Ulike kriterier skaper et inntrykk av sammenligning uten et gyldig valg.[/dont]
[/pair]
[/dos_and_donts]

En tilpasset WordPress-blokk bør redigere hvert par som én post og forhindre publisering når en handling eller grunn mangler.

Eksempler

Bra: likeverdig, handlingsrettet og begrunnet

Parene deler et emne i hver rad: planavgrensning, tidsvindu og bevisstatus. Begge handlingene er spesifikke nok til å vurderes i et utkast, og hver grunn forklarer hva som kan gå galt. En leser kan anvende prinsippet selv når den eksakte prisen, produktet eller perioden endres.

Dårlig: to hauger med kommandoer

Dette mislykkes fordi kolonnene er urelaterte og ulike. «Vær nøyaktig» har ingen observerbar fullføringsbetingelse, mens «Bruk aldri fagsjargong» forbyr språk uten å skille nødvendige termer fra uforklarte termer. Ingen av de negative elementene angir en konsekvens, og den tomme cellen avslører at forfatteren laget to lister i stedet for fire par.

Reparer blokken ved å velge ett emne, og skriv deretter likeverdige rader. For terminologi kunne paret være: «Definer en nødvendig fagterm ved første gangs bruk, fordi definisjonen lar nykommere følge argumentet» og «Ikke erstatt en presis term med et vagt hverdagsuttrykk, fordi erstatningen kan endre betydningen.» Korrigeringen lærer dømmekraft i stedet for å tvinge frem et slagord.

Skjemamarkering og tilgjengelighet

Schema.org gir ingen generell DoAndDont-type. Hold den synlige blokken inne i den omsluttende Article, TechArticle, HowTo eller annen sidestrukturert data når siden faktisk kvalifiserer. Ikke konverter de positive elementene til HowToStep-poster med mindre de danner en ordnet prosedyre, og ikke publiser parene som FAQPage bare fordi de inneholder korte forklaringer.

Bruk opprinnelige overskrifter og lister. Én ytre seksjon får sitt tilgjengelige navn fra emneoverskriften. Hvert par bør være ett listeelement eller en gruppert post som inneholder en synlig «Gjør»-etikett og en synlig «Ikke gjør»-etikett. Bevar hvert par i kildeorden slik at en skjermleserbruker møter anbefalingen og dens tilhørende feil sammen.

Farge og ikoner er tillegg. Grønt kan ikke være det eneste signalet for «Gjør», og et kryss kan ikke være det eneste signalet for «Ikke gjør.» Dekorative ikoner får tom alternativ tekst eller skjules for hjelpeteknologi. Ikke gjør en statisk blokk fokuserbar. Hvis horisontal overlapping er uunngåelig for en eksempeltabell, innehold og merk rulleområdet; produksjonskomponenten bør stable par i stedet.

Kontraksjonen «Don’t» er akseptabelt som synlig redaksjonell tekst. Kodefelt bruker ASCII-sikkert dont der apostrofer ville komplisere attributtnavn. Gjengivere lokaliserer etikettene uten å endre de lagrede handlingene eller grunnene.

Skriveregler

Skriv grunnen før du ferdigstiller kommandoen. Dette tvinger forfatteren til å identifisere leser-, system-, sikkerhets-, etterlevelses- eller vedlikeholdskonsekvensen. Hvis en forsvarlig grunn ikke kan skrives, kan forbudet være preferanse snarere enn veiledning.

Bruk tre til syv par. Hver handling bør uttrykke én observerbar atferd på 110 tegn eller færre der det er praktisk. Gi hver side én grunnsetning på maks 180 tegn. Begrensningene holder de to sidene skannbare; lengre kvalifikasjoner hører hjemme i omkringliggende prosa.

Oppretthold paritet på tvers av fem dimensjoner:

• Emne: begge handlinger adresserer samme beslutning eller artefakt.
• Nivå: en presis markeringsregel kan ikke pares med en bred maksime som «skriv godt.»
• Grammatikk: bruk parallelle imperativer eller parallelle deklarative setninger.
• Bevis: anvend samme faktuelle og kildemessige terskel på begge sider.
• Visuell vekt: ingen side får mer plass, vektlegging, detaljer eller standard synlighet.

Bruk direkte, nøytralt språk. Foretrekk «Ikke publiser en uverifisert pris» fremfor skammende språk som «Bare slurvete forfattere glemmer å verifisere priser.» Unngå sarkasme, frykt og absolutte termer med mindre regelen er genuint absolutt og omfanget er angitt.

Sett aldri disse inni elementet:

• Urelaterte tips lagt til for å fylle én side eller tvinge numerisk symmetri.
• Et forbud uten en konsekvens, et prinsipp eller en erstatningshandling.
• Ordnete prosedyrer, avkrysningsbokser, rangeringer, dommer eller produktfordeler og -begrensninger.
• Sikkerhetskritiske advarsler, juridiske fraskrivelser, nødinstruksjoner eller irreversible handlingsvarsler.
• Vitnesbyrd, lange sitater, medier, skjemaer, handlingsfremmende uttrykk, reklameknapper eller kupongkoder.
• Nestede akkordioner, faner, karuseller, sammenligningstabeller eller en annen gjør-og-ikke-gjør-blokk.
• Påstander om personer eller grupper formulert som moralsk svikt snarere enn observerbar atferd.

Når et krav kommer fra en policy, regulering, test eller ekstern standard, legg til en nærliggende kildenotat. Tilskriv regelen presist nok til at en redaktør kan dobbeltsjekke den; ikke få blokken til å bære et langt siteringsapparat.

Innleggstyper som bruker det

postTypes-frontmatter-matrisen driver denne bruksmatrisen. Inkludering gjør elementet tilgjengelig under den angitte betingelsen; det gjør ikke blokken obligatorisk på hver side av den typen.

QA-sjekkliste

• Blokken har ett avgrenset emne som er tydelig fra nærmeste overskrift.
• Det styrende prinsippet vises før blokken, slik at parene forsterker snarere enn finner opp regelen.
• Det er tre til syv komplette par og nøyaktig samme antall «Gjør»- og «Ikke gjør»-handlinger.
• Hvert par adresserer samme emne, målgruppe, omfang og presisjonsnivå.
• Hvert «Ikke gjør» navngir en realistisk feil og forklarer dens konsekvens eller feilmodus.
• Hvert «Gjør» gir en handlingsrettet erstatning og forklarer hvorfor den fungerer.
• Intet element bare negerer sin partner, gjentar et slagord, eller bruker sirkulær ordlyd.
• Handlinger inneholder én atferd og holder seg nær 110-tegns målet.
• Grunner inneholder én setning og holder seg innenfor 180 tegn.
• Begge sider bruker parallell grammatikk, bevisstandarder, detaljer og visuell vekt.
• Faktakrav identifiserer sin policy, regulering, test eller kilde der nødvendig.
• Blokken inneholder ingen steg, avkrysningstilstander, produktavveininger, alvorlige advarsler, reklame, skjemaer eller nestede komplekse elementer.
• Synlig tekst sier «Gjør» og «Ikke gjør»; farge, posisjon og ikoner er ikke de eneste signalene.
• Responsiv utdata holder hvert par sammen i stedet for å stable alle positive elementer før alle negative elementer.
• Emneoverskriften og parstrukturen forblir forståelige i ren tekst og når stilark eller skript ikke er tilgjengelige.
• Strukturert data beskriver den omsluttende siden kun og finner ikke opp en gjør-og-ikke-gjør-skjematype.
• Skjermbildekommentarer forblir ikke-gjengivende fangstinstruksjoner inntil virkelige eiendeler eksisterer.

FAQ

Akademimalen gjengir de fem spørsmålene som er lagret i denne sidens [[faq]]-frontmatter. De dekker parfullstendighet, numerisk paritet, grunner, strukturert data og antall elementer.