Note Box: Kiedy i jak go używać

Ramka notatki izoluje kontekst, który pomaga czytelnikowi zinterpretować pobliską treść, ale nie zmienia tego, co czytelnik powinien zrobić, jakiego wyniku oczekiwać ani jak poważna jest sytuacja.

Ten przykład renderowany rozwiązuje prawdopodobne pytanie bez dodawania kroku. Czytelnik, który go pominie, nadal może korzystać z raportu poprawnie. Czytelnik, który zauważy różnicę czasu, otrzymuje brakujący kontekst i może kontynuować bez zmiany przepływu pracy.

Dlaczego ten element jest ważny

Czytelnicy skanują stronę według priorytetu wizualnego. Ograniczona notatka mówi: „Ten kontekst może rozwiązać pytanie, ale nie jest to nowa instrukcja”. Taki sygnał zmniejsza wysiłek wymagany do sklasyfikowania dygresji. Czytelnik może na chwilę opuścić główny wątek, przyswoić wyjaśnienie i wrócić w to samo miejsce bez zastanawiania się, czy proces się zmienił.

Element działa tylko wtedy, gdy ta obietnica pozostaje wiarygodna. Jeśli wymagane kroki, komunikaty sprzedażowe, definicje, ostrzeżenia i fakty tła wszystkie otrzymają styl notatki, etykieta przestaje pomagać. Czytelnicy muszą sprawdzać każdą ramkę, aby odkryć, co oznacza, co dodaje więcej obciążenia poznawczego — wysiłku umysłowego związanego z przetwarzaniem informacji — niż zwykła proza by stworzyła.

Etykiety dotkliwości uczą również zachowania poprzez powtarzanie. Gdy nieszkodliwy kontekst otrzymuje kolory ostrzeżenia, czytelnicy wielokrotnie napotykają pilny sygnał bez żadnych znaczących konsekwencji. Uczą się go pomijać. Następne prawdziwe ostrzeżenie konkuruje wtedy z historią fałszywych alarmów. Niewłaściwe używanie stylistyki ostrzeżeń do notatek nie tylko czyni jedną stronę melodramatyczną; osłabia cały język ryzyka witryny.

Dla maszyn typowana notatka zapewnia wyraźną granicę i cel. Narzędzie do migracji treści może zachować blok jako dodatkowy kontekst, zamiast scalać go z krokiem proceduralnym. System wyszukiwania lub agent AI może wyodrębnić notatkę wraz z jej etykietą i treścią, a następnie utrzymać ją podporządkowaną twierdzeniu, które wyjaśnia. Tę relację trudniej odzyskać z akapitu zabarwionego na niebiesko stylistyką specyficzną dla strony.

Możliwość wyodrębnienia wciąż zależy od pisania. „To może wyglądać inaczej” nie jest użyteczne poza swoim akapitem, ponieważ brakuje podmiotu. „Znaczniki czasu w raportach używają UTC, a nie lokalnego czasu widza” jest samodzielne. Zasady pisania elementów mają pierwszeństwo: najpierw zaklasyfikuj fragment według jego celu, a następnie zastosuj zarejestrowany element. Podkreślenie wizualne nigdy nie tworzy typu semantycznego.

Kiedy go używać

Użyj notatki tylko wtedy, gdy wszystkie cztery warunki są spełnione:

1. Fragment wyjaśnia jedno pobliskie stwierdzenie, wartość, instrukcję, przykład lub sekwencję.
2. Pominięcie go nie zmienia wymaganego działania, oczekiwanego wyniku, prawidłowej interpretacji głównego twierdzenia ani poziomu ryzyka.
3. Kontekst odpowiada na prawdopodobne pytanie czytelnika, które w przeciwnym razie przerwałoby zrozumienie.
4. Fragment jest wystarczająco samodzielny, aby pozostał znaczący po wyodrębnieniu wraz z etykietą.

Dobry materiał na notatkę obejmuje konwencję strefy czasowej, alias nazewniczy, granicę zakresu już sugerowaną przez główny tekst, nieszkodliwą różnicę interfejsu między wersjami lub wyjaśnienie oczekiwanego stanu wyświetlania. Na przykład: „Przycisk ma etykietę Zapisz na kontach miesięcznych i Zastosuj na kontach rocznych; oba wysyłają te same ustawienia”. Działanie i wynik czytelnika nie zmieniają się.

Prawie trafienia mają znaczenie, ponieważ „przydatne dodatkowe informacje” to zbyt szeroka definicja:

• Fakt potrzebny do zrozumienia następnego akapitu należy do głównego wyjaśnienia. Ukrycie go w notatce sprawia, że istotne zrozumienie wygląda na opcjonalne.
• Wymaganie wstępne należy umieścić przed procedurą. Jeśli praca nie może rozpocząć się bez dostępu administratora, dostęp nie jest kontekstem dodatkowym.
• Opcjonalna technika, która przyspiesza lub ulepsza pracę, należy do ramki wskazówki . Wskazówka zmienia jakość lub wydajność wyniku; notatka tego nie robi.
• Warunek, który zapobiega usunięciu, kosztowi, ujawnieniu, obrażeniom lub nieprawidłowej pracy, należy do ramki ostrzeżenia . Jej celem jest zmiana zachowania przed wystąpieniem szkody.
• Formalna definicja ustalająca znaczenie terminu należy do elementu definicji lub głównego wyjaśnienia, a nie do notatki.
• Cytat należy umieścić obok twierdzenia, które wspiera. Dowód nie jest dygresją, gdy twierdzenie od niego zależy.
• Promocja, wezwanie do zapisu lub rekomendacja produktu to wezwanie do działania, a nie informacja.

Użyj testu braku zmiany, gdy klasyfikacja jest niepewna: „Czy czytelnik, poznając ten fakt, musi zmienić działanie, oczekiwanie, decyzję lub reakcję bezpieczeństwa?” Jeśli tak, to nie jest notatka. Jeśli nie, zapytaj, czy fakt rozwiązuje rzeczywistą niejednoznaczność. Jeśli nie, usuń go lub pozostaw jako zwykłą prozę, zamiast tworzyć sztuczne podkreślenie.

Gdzie go umieścić

Umieść notatkę bezpośrednio po kompletnym bloku treści, który wyjaśnia. Celem może być akapit, element listy, krok, tabela, próbka kodu lub krótka sekwencja, ale cel musi mieć sens przed pojawieniem się notatki. Notatka dostarcza wtedy dodatkowego kontekstu bez rozbijania celu.

Gdy notatka dotyczy całej sekcji, umieść ją po akapicie otwierającym, który definiuje zakres sekcji. Nazwij ten zakres w pierwszym zdaniu notatki. Gdy dotyczy procedury, umieść ją po akapicie wprowadzającym, a przed pierwszym krokiem, tylko jeśli żadne działanie się nie zmienia; w przeciwnym razie treść jest wymaganiem wstępnym lub ostrzeżeniem. Notatka o wyniku należy po wprowadzeniu wyniku, a nie kilka akapitów później.

Używaj nie więcej niż trzech notatek na stronie i jednej na sekcję. Trzy to górna granica. Jeśli kilka notatek gromadzi się wokół jednego fragmentu, główny tekst prawdopodobnie brakuje wyjaśnienia lub materiał zasługuje na dedykowaną podsekcję.

Notatka nie może znajdować się:

• Między nagłówkiem a jego akapitem otwierającym.
• Między twierdzeniem a dowodem, który je wspiera.
• Między instrukcją a wymaganą kontrolą sukcesu.
• Bezpośrednio obok wskazówki, ostrzeżenia, CTA, banera promocyjnego lub innej notatki.
• Wewnątrz komórki tabeli, odpowiedzi FAQ, cytatu, bloku kodu, panelu akordeonu ani innego wyróżnienia.
• W hero wyłącznie w celu stworzenia zainteresowania wizualnego, z wyjątkiem sytuacji, gdy specyfikacja elementu renderuje wymagany żywy przykład.
• Na końcu strony, gdy jej cel pojawił się znacznie wcześniej.

Jeśli sąsiedztwo utworzyłoby stos ramek, przenieś notatkę do prozy lub przeorganizuj sekcję. Nie rozwiązuj kolizji poprzez zmianę notatki na kolory ostrzeżenia; prezentacja nie naprawi niejasnej relacji treści.

Anatomia

Wyrenderowana notatka ma cztery widoczne lub strukturalne regiony:

1. Etykieta typu: Widoczne słowo „Notatka”, które identyfikuje blok bez polegania na kolorze lub ikonie.
2. Opcjonalny tytuł: Krótka, rzeczowa fraza, która nazywa kontekst, np. „Strefa czasowa” lub „Etykiety interfejsu”.
3. Treść: Jedno samodzielne wyjaśnienie i, gdy przydatne, zdanie łączące je z pobliską treścią.
4. Sąsiedni cel: Kompletny blok lub nazwana sekwencja wyjaśniana. Umiejscowienie niesie tę relację, nawet jeśli nie jest to autorski pole tekstowe.

Granice, tła, ikony, odstępy i style czcionek należą do renderera. Autorzy dostarczają znaczenie, a nie instrukcje kolorystyczne czy dekoracyjne symbole.

Przykłady projektowe

Wspierane warianty testują treść i zachowanie responsywne. Nie tworzą one różnych poziomów ważności.

Domyślny: Renderer dostarcza „Notatka”, a treść zawiera jedno wyjaśnienie. Używaj tej formy najczęściej.

Niestandardowy tytuł: Rzeczowy tytuł identyfikuje temat. Nie zwiększa dotkliwości ani nie zastępuje semantyki notatki komponentu.

Maksimum dwóch akapitów: Pierwszy akapit określa kontekst; drugi wyjaśnia granicę lub nieszkodliwy wyjątek. Dłuższe wyjaśnienia stają się zwykłą treścią.

Odnośnik w tekście: Jedna wartość kodu w tekście lub opisowy link może wyjaśniać cel. Żaden z nich nie powinien zamieniać notatki w dokumentację w dokumentacji.

Wąski widok: Etykieta, tytuł i treść zachowują swoją kolejność czytania, zawijają się normalnie i pozostają zrozumiałe bez obramowania lub ikony.

Parametry

Model treści oddziela ustalony typ semantyczny, opcjonalne nazewnictwo, treść i relację z pobliską treścią. „Źródło” określa, skąd autor lub renderer uzyskuje wartość.

Tytuł jest opcjonalny, ponieważ „Notatka” jest zwykle wystarczająca. Pierwszy nagłówek przenośnej dyrektywy może mapować się na title zgodnie z domyślnymi zasadami treści, ale zwięzła forma atrybutu jest preferowana dla tego elementu. Wszystko inne mapuje się na body. Obecna implementacja Hugo akceptuje pozycyjny typ lub nazwany type, plus opcjonalny nazwany title; nigdy nie mieszaj parametrów pozycyjnych i nazwanych.

Składnia i przykłady kodu

Te formy niosą ten sam typ, tytuł i treść. Prezentacja platformy może się różnić, ale wyjaśnienie musi pozostać notatką.

Przenośna dyrektywa Markdown

:::note{title="Strefa czasowa"}
Znaczniki czasu w raportach używają UTC. Filtry i obliczenia nie zmieniają się, gdy lokalna strefa czasowa widza jest inna.
:::

Nazwa dyrektywy dostarcza typ, atrybut dostarcza opcjonalny tytuł, a zamknięty Markdown dostarcza treść.

Shortcode Hugo

{{< callout type="note" title="Strefa czasowa" >}}Znaczniki czasu w raportach używają UTC. Filtry i obliczenia nie zmieniają się, gdy lokalna strefa czasowa widza jest inna.{{< /callout >}}

Ten przykład używa tylko nazwanych parametrów. Bez niestandardowego tytułu forma pozycyjna callout note jest prawidłowa, a renderer dostarcza etykietę „Notatka”.

Blok lub shortcode WordPress

<!-- wp:amicited/note {"title":"Strefa czasowa"} -->
<p>Znaczniki czasu w raportach używają UTC. Filtry i obliczenia nie zmieniają się, gdy lokalna strefa czasowa widza jest inna.</p>
<!-- /wp:amicited/note -->

[note title="Strefa czasowa"]Znaczniki czasu w raportach używają UTC. Filtry i obliczenia nie zmieniają się, gdy lokalna strefa czasowa widza jest inna.[/note]

Zarejestrowany blok jest preferowaną implementacją WordPress. Shortcode jest akceptowalny, gdy instalacja wyraźnie go wspiera; systemy importujące nie mogą spłaszczać notatki do ostrzeżenia ani wnioskować innego typu na podstawie jej kolorów.

Przykłady

Dobrze: nieszkodliwa różnica interfejsu

To jest dobre, ponieważ odpowiada na prawdopodobne pytanie dotyczące interfejsu, zachowując jednocześnie to samo działanie i wynik. Nazywa obie etykiety, mówi, gdzie każda występuje, i potwierdza ich równoważne zachowanie. Notatka ma sens nawet po wyodrębnieniu z otaczającej procedury.

Źle: ostrzeżenie przebrane za informację

Notatka — Usunięcie obszaru roboczego: Usunięcie obszaru roboczego trwale usuwa jego raporty. Wyeksportuj wymagane rekordy przed kontynuowaniem.

To jest złe, ponieważ konsekwencja wymaga zmiany zachowania przed nieodwracalnym działaniem. Spokojne sformułowanie i neutralna etykieta nie czynią tego dodatkowym. To musi być ostrzeżenie umieszczone przed kontrolką usuwania, z celem, konsekwencją i działaniem zapobiegawczym wyraźnie określonym.

Inna zła notatka mówi: „Eksport musi zawierać wszystkie wymagane kolumny”. To jest kryterium akceptacji. Umieść wymagane kolumny w instrukcji lub tabeli specyfikacji. Trzecia mówi: „Możesz zaoszczędzić czas, filtrując eksport najpierw”. To jest opcjonalna porada poprawiająca wynik, a zatem wskazówka. Prawidłowa klasyfikacja jest ważniejsza niż różnorodność wizualna.

Znaczniki schematu i dostępność

Ramka notatki nie ma dedykowanego typu ani właściwości Schema.org. Pozostaje widoczną treścią w ramach nadrzędnego Article, TechArticle, produktu lub innego prawdziwego schematu na poziomie strony. Nie twórz samodzielnego obiektu JSON-LD dla niej. Gdy notatka wyjaśnia krok, trzymaj ją oddzielnie od HowToStep.text, chyba że wyjaśnienie jest niezbędne do wykonania kroku; jeśli jest niezbędne, to od początku nie była to opcjonalna treść notatki.

Statyczna notatka nie potrzebuje role="alert", regionu ARIA live ani wymuszonego ogłoszenia. Te mechanizmy komunikują pilność lub dynamiczną zmianę, podczas gdy notatka występuje w normalnej kolejności dokumentu i niesie niepilny kontekst. Agresywne ogłaszanie błędnie przedstawiłoby jej ważność i uczyniłoby wyjście technologii asystujących bardziej hałaśliwym.

Wyrenderuj widoczną etykietę jako tekst w Document Object Model, a nie jako obraz tła, podpowiedź tylko z ikoną ani dekorację generowaną przez CSS. Jeśli używana jest rola region, połącz jej dostępną nazwę z widoczną etykietą lub niestandardowym tytułem. Kolejność czytania to etykieta, opcjonalny tytuł, a następnie treść. Kolor i ikony mogą wzmacniać typ, ale nie mogą być jedynym rozróżnieniem od wskazówek i ostrzeżeń.

Przy 200% powiększeniu tekstu i na wąskim widoku treść musi zawijać się bez przewijania poziomego. Linki wymagają opisowego tekstu kotwicy i muszą być dostępne z klawiatury. Kod w tekście musi pozostać czytelny przy wysokim kontraście. Istotne informacje nie mogą istnieć tylko na zrzucie ekranu anatomii lub w tekście alternatywnym ikony.

Zasady pisania

Celuj w 15–60 słów. Twarde maksimum to 90 słów w nie więcej niż dwóch krótkich akapitach. Dłuższy fragment zwykle zasługuje na integrację z głównym wyjaśnieniem; bardzo krótka notatka to często etykieta bez użytecznego kontekstu.

Pisz jedno wyjaśnienie na ramkę w spokojnym, rzeczowym tonie. Podaj temat w pierwszym zdaniu, a następnie wyjaśnij nieszkodliwą różnicę lub granicę. Preferuj precyzyjne sformułowania, takie jak „Znaczniki czasu używają UTC” zamiast potocznego wypełniacza, takiego jak „Tak tylko żebyś wiedział”. Podaj powód przed jakąkolwiek regułą interpretacyjną: „Zarchiwizowane projekty pozostają widoczne w historycznych raportach, więc ich sumy mogą nadal pojawiać się w minionych zakresach dat.”

Notatka może zawierać zwykłe podkreślenie, do dwóch krótkich wartości kodu w tekście i co najwyżej jeden opisowy link. Nigdy nie może zawierać:

• Wymaganego kroku, wymagania wstępnego, reguły walidacji, kryterium sukcesu ani instrukcji odzyskiwania.
• Istotnego ryzyka, nieodwracalnej konsekwencji, warunku bezpieczeństwa, instrukcji prawnej ani ujawnienia kosztów.
• Opcjonalnej porady, której celem jest poprawa szybkości, jakości, dokładności lub wygody.
• Pełnej definicji, dowodu potrzebnego do poparcia twierdzenia ani listy źródeł.
• Więcej niż jednego niezależnego wyjaśnienia.
• Tabeli, bloku kodu, formularza, przycisku, CTA, referencji, promocji ani zagnieżdżonego elementu.
• Żartów, alarmistycznego języka, dekoracyjnych emoji ani słów takich jak „krytyczne” i „niebezpieczeństwo”.

Nie tytułuj każdej notatki „Ważne”. Ważność nie jest celem elementu, a to słowo fałszywie zbliża się do dotkliwości ostrzeżenia. Użyj „Notatka” lub rzeczowego tytułu. Nigdy nie używaj notatki do ratowania niejasnej prozy: najpierw napraw główne wyjaśnienie, a następnie pozostaw notatkę tylko wtedy, gdy pozostaje rzeczywiście dodatkowa niejednoznaczność.

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

Frontmatter postTypes wymienia formaty, w których kontekst dodatkowy występuje regularnie. Włączenie pozostaje opcjonalne; tabela definiuje dozwolone zadanie i pozycję, a nie wymagane miejsce.

Inne typy wpisów mogą używać notatki, gdy ten sam test braku zmiany jest spełniony. Znajdowanie się na liście nie uzasadnia dodawania notatki dla rytmu wizualnego, a pominięcie nie zamienia ostrzeżenia w notatkę.

Lista kontrolna QA

Przed publikacją zweryfikuj każdy element:

• Blok wyjaśnia jeden pobliski fragment i nie zmienia działania, wyniku, priorytetu, interpretacji ani ryzyka.
• Kontekst odpowiada na prawdopodobne pytanie czytelnika, zamiast powtarzać cel.
• Wymagane informacje pozostają w głównej treści.
• Notatka znajduje się bezpośrednio po swoim kompletnym celu lub po akapicie zakresu dla nazwanej sekwencji.
• Nie oddziela nagłówka od jego wprowadzenia, twierdzenia od dowodu ani instrukcji od kontroli sukcesu.
• Żadne ostrzeżenie, wskazówka, CTA, baner ani druga notatka nie znajdują się bezpośrednio obok.
• Strona ma nie więcej niż trzy notatki, a sekcja nie więcej niż jedną.
• Treść celuje w 15–60 słów, pozostaje poniżej 90 słów i zawiera jedno wyjaśnienie.
• Widoczna etykieta tekstowa działa bez koloru, obramowania, ikony ani obrazu.
• Tekst pozostaje znaczący po wyodrębnieniu z etykietą, ale bez otaczającej stylistyki.
• Ramka nie używa roli alert ani regionu live przy ładowaniu strony.
• Mapowania Markdown, Hugo i WordPress zachowują typ, tytuł, treść i umiejscowienie.
• Parametry Hugo są w całości pozycyjne lub w całości nazwane; nigdy nie są mieszane.
• Wewnątrz nie pojawia się żaden nieobsługiwany zagnieżdżony komponent, blok kodu, tabela, formularz ani działanie promocyjne.
• Znaczniki zrzutów ekranu żądają przyszłych przechwyceń bez renderowania nieistniejących zasobów.

FAQ

Jaka jest różnica między notatką, wskazówką a ostrzeżeniem? Notatka wyjaśnia, niczego nie zmieniając. Wskazówka oferuje opcjonalne ulepszenie. Ostrzeżenie zmienia zachowanie, aby zapobiec szkodzie, stracie, kosztowi, ujawnieniu lub nieprawidłowej pracy. Klasyfikuj według konsekwencji pominięcia bloku, a nie według jego koloru.

Czy ramka notatki może zawierać wymagane informacje? Nie. Wymagane informacje należą do głównej treści, gdzie każdy czytelnik napotyka je w sekwencji. Notatka może wyjaśniać nieszkodliwą różnicę, ale jej pominięcie nie może czynić zadania lub interpretacji nieprawidłowymi.

Ile ramek notatki powinna zawierać jedna strona? Używaj nie więcej niż trzech na stronę i jednej na sekcję. Większość stron potrzebuje mniej. Powtarzające się notatki wskazują, że główne wyjaśnienie wymaga restrukturyzacji.

Czy ramka notatki powinna używać kolorów ostrzeżenia lub roli alertu? Nie. Prezentacja ostrzeżenia sygnalizuje materialną konsekwencję, a role="alert" sygnalizuje pilną informację dynamiczną. Zastosowanie któregoś z nich do rutynowego kontekstu uczy ludzi ignorować prawdziwy sygnał i wprowadza w błąd użytkowników technologii asystujących.

Czy ramka notatki może zawierać linki lub kod? Może zawierać jeden opisowy link lub do dwóch krótkich wartości kodu w tekście, gdy bezpośrednio wyjaśniają cel. Użyj głównej treści dla bloków kodu, tabel, formularzy lub wieloetapowej dokumentacji.

Notatka zasługuje na swoją granicę, rozwiązując rzeczywistą niejednoznaczność, pozostawiając jednocześnie kurs czytelnika niezmieniony. Zachowaj ją spokojną, sąsiednią, samodzielną i wizualnie odróżnialną od porad i ryzyka.