Zasady „Rób” i „Nie rób”: Sparowane reguły wskazówek

Blok „rób” i „nie rób” łączy zalecane działanie z błędem o tym samym zakresie i wyjaśnia, dlaczego błąd jest nieudany. Jego wartość wynika z kontrastu: błędna wersja ujawnia kuszący sposób popełnienia błędu, podczas gdy poprawna wersja daje czytelnikowi natychmiastowy zamiennik.

Ten pokazany przykład jest modelem produkcyjnym. Każdy wiersz dotyczy jednego tematu na tym samym poziomie szczegółowości. „Nie rób” wymienia realistyczny błąd i jego konsekwencję; „Rób” dostarcza użytecznej korekty. Etykiety, a nie kolor czy ikony, niosą rozróżnienie.

Dlaczego ten element jest ważny

Reguły są łatwiejsze do zrozumienia, gdy czytelnicy widzą granicę, której mają przestrzegać. Sama pozytywna instrukcja może wydawać się abstrakcyjna: „Używaj konkretnych dowodów” nie ujawnia, co jest zbyt ogólne. Sama negatywna instrukcja powoduje tarcie: „Nie wysuwaj niepopartych twierdzeń” mówi, czego unikać, ale pozostawia następny krok niejasnym. Połączenie obu zamienia granicę w wybór, na którym czytelnik może działać.

Błędna wersja jest pouczająca, ponieważ często przypomina to, co zapracowana osoba napisałaby naturalnie. Pokazanie tego bliskiego błędu pomaga czytelnikowi rozpoznać go we własnej pracy. Powód jest równie ważny. „Nie używaj niejasnego języka” wymaga posłuszeństwa; „Nie pisz »szybko« bez podania mierzonego zadania, ponieważ czytelnicy nie mogą tego zweryfikować ani porównać” uczy zasady, którą można przenieść na nowe przykłady.

Parzystość oznacza, że obie strony dotyczą równoważnych tematów, liczby elementów, szczegółowości i wagi redakcyjnej. Zapobiega to sytuacji, w której dopracowana kolumna „Rób” stoi obok sterty niepowiązanych ostrzeżeń. Czytelnicy mogą przejrzeć jedną parę, zrozumieć kontrast i kontynuować bez zapamiętywania elementu z innego miejsca na stronie.

Wyodrębnialność maszynowa to zdolność oprogramowania do izolowania treści przy jednoczesnym zachowaniu jej znaczenia i relacji. Widoczne nagłówki, struktura listy i wyrównane pary w wierszach pozwalają systemom wyszukiwania i wyszukarkom odpowiedzi odzyskać stwierdzenia takie jak: „W przypadku cen podaj nazwę planu i datę; unikaj niedatowanych kwot, ponieważ ich zakres jest niemożliwy do zweryfikowania.” Jeśli obie strony zawierają niepowiązane punkty lub powód jest sugerowany jedynie ikoną, ekstrakcja może zachować polecenie, tracąc zastrzeżenie, które czyni je bezpiecznym.

Przed wyborem tego bloku postępuj zgodnie z zasadami pisania elementów . Cel ma pierwszeństwo przed wyglądem. Treści, które przede wszystkim ostrzegają przed bezpośrednim zagrożeniem, pozostają ostrzeżeniem; sekwencja pozostaje listą kroków; skończony zestaw kontroli ukończenia pozostaje listą kontrolną. Dwie kolorowe kolumny nie zmieniają tych celów w zestawienie „rób” i „nie rób”.

Kiedy go używać

Używaj tego elementu, gdy czytelnicy muszą odróżnić zalecaną praktykę od prawdopodobnego, mającego konsekwencje błędu. Kontrast powinien redukować niejednoznaczność skuteczniej niż pojedyncza instrukcja. Odpowiednie tematy obejmują standardy redakcyjne, konwencje implementacyjne, kontrole jakości, zachowanie projektu, obsługę danych i wybory procesowe.

Wszystkie poniższe warunki powinny być spełnione:

1. Każdy błąd ma odpowiedzialne działanie zastępcze.
2. Powód unikania błędu można wyrazić w jednym krótkim zdaniu.
3. Elementy są niezależnymi wskazówkami, a nie krokami, które należy wykonać w kolejności.
4. Obie strony mogą używać tego samego zakresu i poziomu szczegółowości.

Przypadki graniczne są częste:

• Zalety i wady: korzyści i ograniczenia oceniają jedną opcję. „Rób” i „nie rób” instruują zachowanie czytelnika. „Obejmuje nieograniczone projekty” to zaleta, a nie „rób”.
• Ostrzeżenie: poważna lub nieodwracalna konsekwencja wymaga bezpośredniego wyeksponowania i reakcji, a nie równoważnej kolumny towarzyszącej.
• Lista kontrolna: lista kontrolna śledzi, czy wymagana praca została wykonana. Jej stan niezaznaczony nie jest „nie rób”.
• Tabela porównawcza: tabela ocenia kilka opcji według wspólnych kryteriów. Nie określa poprawnego i niepoprawnego zachowania.
• Przed i po: dwa przykłady mogą pokazać edycję bez wyrażania reguły zachowania wielokrotnego użytku. Używaj „rób” i „nie rób” tylko wtedy, gdy kontrast uczy ogólnej praktyki.
• Dowolny styl redakcyjny: jeśli nie można wyjaśnić żadnej konsekwencji dla czytelnika, systemu, zgodności lub utrzymania, udokumentuj konwencję jako regułę, zamiast udawać, że alternatywa jest błędem.

Nie używaj bloku do tworzenia sztucznej opozycji. „Pisz jasno; nie pisz niejasno” powtarza tę samą abstrakcję i niczego nie uczy. Błędna strona musi być na tyle kusząca, by została rozpoznana, i na tyle konkretna, by można ją było zdiagnozować.

Gdzie go umieścić

Umieść blok po tym, jak strona zdefiniuje zadanie, odbiorców i wszelkie terminy niezbędne do zrozumienia wskazówek. Powinien znajdować się bezpośrednio po wyjaśnieniu lub demonstracji, którą podsumowuje, lub pod koniec sekcji jako praktyczne podsumowanie przed podjęciem działania przez czytelnika.

Dokładne zasady umieszczania:

• Wprowadź jeden temat w najbliższym nagłówku. Każda para musi mieć sens w ramach tego tematu, bez zapożyczania zakresu z odległego akapitu.
• Umieść blok po nadrzędnej zasadzie, a przed listą kontrolną wdrożenia lub następnym działaniem. Czytelnicy powinni zrozumieć „dlaczego”, zanim zweryfikują ukończenie.
• W powtarzających się sekcjach używaj tej samej pozycji i limitów par. Przesuwanie bloku w nieprzewidywalny sposób utrudnia skanowanie między tematami.
• Zachowaj sparowane listy razem w kolejności źródłowej i układzie wizualnym. Tekst wyjaśniający może następować po pełnym bloku, ale nie może dzielić jego stron.

Nie może znajdować się bezpośrednio obok innego dwukolumnowego elementu decyzyjnego, ponieważ sąsiednie siatki zaciemniają, które etykiety i wiersze należą do siebie. Nie umieszczaj referencji, banera promocyjnego, formularza ani wezwania do działania między stronami „Rób” i „Nie rób”. Nie umieszczaj go jako pierwszej znaczącej treści na stronie, gdy reguły zależą od terminów lub kontekstu, którego czytelnik jeszcze nie otrzymał.

Anatomia

Legenda wyrenderowanego bloku

1. Nagłówek tematu: nazywa ograniczone zadanie lub decyzję wspólną dla wszystkich par.
2. Etykieta „Rób”: widoczny tekst identyfikujący zalecane zachowanie; ikona lub zielone oznaczenie są uzupełnieniem.
3. Etykieta „Nie rób”: widoczny tekst identyfikujący zachowanie, którego należy unikać; interpunkcja stosuje zlokalizowaną formę redakcyjną.
4. Instrukcja działania: jedno polecenie w trybie rozkazującym lub stwierdzenie, które nazywa obserwowalne zachowanie.
5. Uzasadnienie: jedno zdanie łączące instrukcję z konsekwencją, sposobem zawodzenia lub nadrzędną zasadą.
6. Relacja pary: kolejność źródłowa i układ zachowują, które „Rób” odpowiada któremu „Nie rób”.
7. Opcjonalna notatka źródłowa: identyfikuje politykę, test, regulację lub dowód regulujący wymagania merytoryczne.

Autor dostarcza temat, pary i uzasadnienia. Mechanizm renderujący zapewnia równą prezentację, responsywne układanie, dostępne etykiety i dekoracyjne ikony tam, gdzie to odpowiednie.

Przykłady projektowe

Poniższe warianty stanowią kompletny wspierany zestaw. Zmieniają gęstość i układ, nigdy parzystość ani kontrakt uzasadniania.

Standardowe sparowane wiersze

Używaj od trzech do siedmiu poziomo wyrównanych wierszy na szerokich ekranach. Każdy wiersz zawiera jedno „Rób” i jedno „Nie rób” na ten sam temat.

Sparowane pary na urządzeniach mobilnych (układ pionowy)

Przy wąskich szerokościach zachowuj każdą parę razem: „Rób”, potem „Nie rób”, potem następna para. Umieszczenie wszystkich pozytywnych elementów przed wszystkimi negatywnymi ukryłoby korespondencję.

Wariant z przykładem

Używaj, gdy dokładny język, znaczniki lub zachowanie interfejsu są bardziej przydatne niż abstrakcyjne polecenie. Każda strona pokazuje jeden krótki przykład, po którym następuje jego uzasadnienie. Kod pozostaje zaznaczalnym tekstem.

Zwarty wariant podsumowujący

Używaj tylko wtedy, gdy nadrzędne uzasadnienia zostały już wyjaśnione bezpośrednio powyżej. Uzasadnienie nadal pojawia się w każdym elemencie, ale w krótkiej frazie, a nie w osobnym akapicie.

Nie twórz wariantów tylko z ikonami, karuzelą, zakładkami ani niezależnie zwijanych. Oddzielają one parę, ukrywają jedną stronę lub uzależniają porównanie od interakcji.

Parametry

Kontrakt modeluje pary, a nie dwie niepowiązane listy. „Źródło” opisuje, skąd mechanizm renderujący pobiera każdą wartość.

Pierwszy nagłówek w treści mapuje się na heading. Każda zagnieżdżona pair posiada oba działania i oba uzasadnienia. Model źródła nie może przechowywać wszystkich pozytywnych elementów oddzielnie od wszystkich negatywnych, ponieważ czyni to korespondencję wierszy zależną od pozycji w tablicy i łatwą do zerwania podczas edycji.

Składnia i przykłady kodu

Wszystkie trzy formaty zachowują ten sam temat, kolejność par, działania i uzasadnienia. Nie wnioskują uzasadnienia z działania ani nie tworzą automatycznie pozytywnego elementu.

Przenośna dyrektywa Markdown

:::dos-and-donts
## Pisanie porównań

::item{do="Podaj dokładny plan i datę sprawdzenia" dont="Nie publikuj niedatowanej ceny"}
### Rób
Fakty handlowe się zmieniają, więc zakres pozwala czytelnikom zweryfikować i wykorzystać twierdzenie.

### Nie rób
Czytelnicy nie są w stanie stwierdzić, jakiego planu lub okresu dotyczy niedatowana kwota.
::

::item{do="Porównuj oba produkty według tego samego kryterium" dont="Nie porównuj niepowiązanych możliwości"}
### Rób
Wspólna miara sprawia, że różnica jest znacząca.

### Nie rób
Różne kryteria stwarzają pozory porównania bez możliwości podjęcia właściwej decyzji.
::
:::

Ten element nadpisuje domyślne mapowanie elementów: nadrzędny nagłówek dostarcza heading; atrybuty elementów dostarczają działania; pierwsze podnagłówki Rób i Nie rób mapują następujący po nich tekst na dwa uzasadnienia.

Shortcode Hugo

Żaden produkcyjny shortcode Hugo nie implementuje obecnie kontraktu sparowanych rekordów. Dopóki taki nie istnieje, renderuj semantyczny HTML jak w przykładzie na żywo, zamiast używać dwóch niepowiązanych pomocników list. Docelowy adapter to:

{{< dos-and-donts >}}
## Pisanie porównań

{{< do-dont-pair do="Podaj dokładny plan i datę sprawdzenia" dont="Nie publikuj niedatowanej ceny" >}}
### Rób
Fakty handlowe się zmieniają, więc zakres pozwala czytelnikom zweryfikować i wykorzystać twierdzenie.
### Nie rób
Czytelnicy nie są w stanie stwierdzić, jakiego planu lub okresu dotyczy niedatowana kwota.
{{< /do-dont-pair >}}
{{< /dos-and-donts >}}

Przyszły mechanizm renderujący musi wyprodukować jeden oznakowany region z listą sparowanych rekordów. Nie może tworzyć dwóch tablic i łączyć ich według indeksu po renderowaniu.

Blok lub shortcode WordPress

[dos_and_donts heading="Pisanie porównań" variant="standard"]
[pair]
[do action="Podaj dokładny plan i datę sprawdzenia"]Fakty handlowe się zmieniają, więc zakres pozwala czytelnikom zweryfikować i wykorzystać twierdzenie.[/do]
[dont action="Nie publikuj niedatowanej ceny"]Czytelnicy nie są w stanie stwierdzić, jakiego planu lub okresu dotyczy niedatowana kwota.[/dont]
[/pair]
[pair]
[do action="Porównuj oba produkty według tego samego kryterium"]Wspólna miara sprawia, że różnica jest znacząca.[/do]
[dont action="Nie porównuj niepowiązanych możliwości"]Różne kryteria stwarzają pozory porównania bez możliwości podjęcia właściwej decyzji.[/dont]
[/pair]
[/dos_and_donts]

Niestandardowy blok WordPress powinien umożliwiać edycję każdej pary jako jednego rekordu i uniemożliwiać publikację, gdy brakuje działania lub uzasadnienia.

Przykłady

Dobrze: równoważne, wykonalne i uzasadnione

Pary dzielą temat w każdym wierszu: zakres planu, okno czasowe i status dowodów. Oba działania są wystarczająco konkretne, aby można je było ocenić w wersji roboczej, a każde uzasadnienie wyjaśnia, co może pójść źle. Czytelnik może zastosować zasadę, nawet gdy zmienia się dokładna cena, produkt lub okres.

Źle: dwie sterty poleceń

| Upraszczaj | Unikaj zbyt wielu linków | | Sprawdzaj fakty | — |

To jest niepoprawne, ponieważ kolumny są niepowiązane i nierówne. „Bądź dokładny” nie ma obserwowalnego warunku ukończenia, podczas gdy „Nigdy nie używaj żargonu” zakazuje języka bez rozróżniania terminów niezbędnych od niewyjaśnionych. Żaden z negatywnych elementów nie podaje konsekwencji, a pusta komórka ujawnia, że autor stworzył dwie listy, a nie cztery pary.

Napraw blok, wybierając jeden temat, a następnie pisząc równoważne wiersze. W przypadku terminologii para mogłaby brzmieć: „Zdefiniuj niezbędny termin specjalistyczny przy pierwszym użyciu, ponieważ definicja pozwala nowicjuszom śledzić wywód” oraz „Nie zastępuj precyzyjnego terminu niejasnym, codziennym wyrażeniem, ponieważ zastąpienie może zmienić znaczenie.” Korekta uczy osądu zamiast egzekwowania sloganu.

Znaczniki schematu i dostępność

Schema.org nie udostępnia ogólnego typu DoAndDont. Zachowaj widoczny blok wewnątrz otaczającego znacznika Article, TechArticle, HowTo lub innych danych strukturalnych na poziomie strony, jeśli ta strona rzeczywiście się kwalifikuje. Nie konwertuj pozytywnych elementów na rekordy HowToStep, chyba że tworzą one uporządkowaną procedurę, i nie publikuj par jako FAQPage tylko dlatego, że zawierają krótkie wyjaśnienia.

Używaj natywnych nagłówków i list. Jedna zewnętrzna sekcja otrzymuje swoją dostępną nazwę z nagłówka tematu. Każda para powinna być jednym elementem listy lub zgrupowanym rekordem zawierającym widoczną etykietę „Rób” i widoczną etykietę „Nie rób”. Zachowaj każdą parę w kolejności źródłowej, aby użytkownik czytnika ekranu spotkał zalecenie i pasujący do niego błąd razem.

Kolor i ikony są uzupełnieniem. Zielony nie może być jedynym sygnałem dla „Rób”, a krzyżyk nie może być jedynym sygnałem dla „Nie rób”. Ikony dekoracyjne otrzymują pusty tekst alternatywny lub są ukryte przed technologiami asystującymi. Nie czyń statycznego bloku możliwym do fokusowania. Jeśli nie można uniknąć poziomego przepełnienia w przypadku tabeli z przykładami, zamknij i oznakuj obszar przewijania; komponent produkcyjny powinien zamiast tego układać pary pionowo.

Skrót „Nie rób” jest akceptowalny jako widoczny tekst redakcyjny. Pola kodu używają bezpiecznego dla ASCII dont tam, gdzie apostrofy komplikowałyby nazwy atrybutów. Mechanizmy renderujące lokalizują etykiety bez zmiany przechowywanych działań lub uzasadnień.

Zasady pisania

Napisz uzasadnienie przed sfinalizowaniem polecenia. To zmusza autora do zidentyfikowania konsekwencji dla czytelnika, systemu, bezpieczeństwa, zgodności lub utrzymania. Jeśli nie można napisać możliwego do obrony uzasadnienia, zakaz może być preferencją, a nie wskazówką.

Używaj od trzech do siedmiu par. Każde działanie powinno wyrażać jedno obserwowalne zachowanie w 110 znakach lub mniej, gdzie to praktyczne. Każdej stronie podaj jedno zdanie uzasadnienia o długości nieprzekraczającej 180 znaków. Limity te zapewniają skanowalność obu stron; dłuższe zastrzeżenia należą do otaczającej prozy.

Zachowaj parzystość w pięciu wymiarach:

• Temat: oba działania dotyczą tej samej decyzji lub artefaktu.
• Poziom szczegółowości: precyzyjna reguła znaczników nie może być sparowana z ogólną maksymą, taką jak „pisz dobrze”.
• Gramatyka: używaj równoległych trybów rozkazujących lub równoległych stwierdzeń oznajmujących.
• Dowody: zastosuj ten sam próg merytoryczny i źródłowy dla obu stron.
• Waga wizualna: żadna ze stron nie otrzymuje więcej przestrzeni, podkreślenia, szczegółów ani domyślnej widoczności.

Używaj bezpośredniego, neutralnego języka. Przedkładaj „Nie publikuj niezweryfikowanej ceny” nad zawstydzający język, taki jak „Tylko nieostrożni autorzy zapominają zweryfikować ceny.” Unikaj sarkazmu, strachu i absolutnych sformułowań, chyba że reguła jest naprawdę bezwzględna, a jej zakres jest określony.

Nigdy nie umieszczaj wewnątrz elementu:

• Niepowiązanych porad dodanych w celu wypełnienia jednej strony lub wymuszenia symetrii liczbowej.
• Zakazu bez konsekwencji, zasady lub działania zastępczego.
• Uporządkowanych procedur, pól wyboru, ocen, werdyktów ani zalet i ograniczeń produktów.
• Krytycznych ostrzeżeń bezpieczeństwa, wyłączeń odpowiedzialności prawnej, instrukcji awaryjnych ani powiadomień o nieodwracalnych działaniach.
• Referencji, długich cytatów, multimediów, formularzy, wezwań do działania, przycisków promocyjnych ani kodów kuponowych.
• Zagnieżdżonych akordeonów, zakładek, karuzel, tabel porównawczych ani innego bloku „rób” i „nie rób”.
• Twierdzeń o osobach lub grupach przedstawianych jako porażka moralna, a nie obserwowalne zachowanie.

Gdy wymóg wynika z polityki, regulacji, testu lub standardu zewnętrznego, dodaj pobliską notatkę źródłową. Przypisz regułę wystarczająco precyzyjnie, aby redaktor mógł ją ponownie sprawdzić; nie obciążaj bloku rozbudowanym aparatem cytowań.

Typy wpisów, które go używają

Tablica postTypes w metadanych frontmatter steruje tą macierzą użycia. Umieszczenie w niej elementu udostępnia go pod określonym warunkiem; nie czyni bloku obowiązkowym na każdej stronie tego typu.

Lista kontrolna QA

• Blok ma jeden ograniczony temat, który jest jasny z najbliższego nagłówka.
• Nadrzędna zasada pojawia się przed blokiem, więc pary wzmacniają, a nie wymyślają regułę.
• Jest od trzech do siedmiu kompletnych par i dokładnie taka sama liczba działań „Rób” i „Nie rób”.
• Każda para dotyczy tego samego tematu, odbiorców, zakresu i poziomu szczegółowości.
• Każde „Nie rób” wymienia realistyczny błąd i wyjaśnia jego konsekwencję lub sposób zawodzenia.
• Każde „Rób” dostarcza wykonalnego zamiennika i wyjaśnia, dlaczego działa.
• Żaden element nie jest po prostu zaprzeczeniem swojego partnera, nie powtarza sloganu ani nie używa kolistej argumentacji.
• Działania zawierają jedno zachowanie i mieszczą się w pobliżu celu 110 znaków.
• Uzasadnienia zawierają jedno zdanie i mieszczą się w 180 znakach.
• Obie strony używają równoległej gramatyki, standardów dowodowych, szczegółowości i wagi wizualnej.
• Wymagania merytoryczne identyfikują swoją politykę, regulację, test lub źródło tam, gdzie to konieczne.
• Blok nie zawiera kroków, stanów zaznaczenia, kompromisów produktowych, poważnych ostrzeżeń, promocji, formularzy ani zagnieżdżonych złożonych elementów.
• Widoczny tekst to „Rób” i „Nie rób”; kolor, pozycja i ikony nie są jedynymi sygnałami.
• Responsywne wyjście zachowuje każdą parę razem, zamiast układać wszystkie pozytywne elementy przed wszystkimi negatywnymi.
• Nagłówek tematu i struktura par pozostają zrozumiałe w czystym tekście oraz gdy style lub skrypty są niedostępne.
• Dane strukturalne opisują tylko otaczającą stronę i nie wymyślają typu schematu dla „rób” i „nie rób”.
• Komentarze ze zrzutami ekranu pozostają instrukcjami przechwytywania, które nie są renderowane, dopóki nie istnieją rzeczywiste zasoby.

FAQ

Szablon academy renderuje pięć pytań przechowywanych w [[faq]] w metadanych tej strony. Dotyczą one kompletności par, parzystości liczbowej, uzasadnień, danych strukturalnych i liczby elementów.