Poznámkový box: Kedy a ako ho používať

Poznámkový box izoluje kontext, ktorý pomáha čitateľovi interpretovať okolitý obsah, ale nemení to, čo by mal čitateľ urobiť, aký výsledok očakávať ani aká vážna je situácia.

Tento vykreslený príklad odpovedá na pravdepodobnú otázku bez pridania kroku. Čitateľ, ktorý ho preskočí, môže správu používať správne. Čitateľ, ktorý si všimne časový rozdiel, získa chýbajúci kontext a môže pokračovať bez zmeny pracovného postupu.

Prečo na tomto prvku záleží

Čitatelia skenujú stránku podľa vizuálnej priority. Ohraničená poznámka hovorí: „Tento kontext môže objasniť otázku, ale nie je to nový pokyn.“ Tento signál znižuje úsilie potrebné na klasifikáciu odbočky. Čitateľ môže nakrátko opustiť hlavný argument, vstrebať objasnenie a vrátiť sa na to isté miesto bez premýšľania, či sa proces zmenil.

Prvok funguje len vtedy, keď tento sľub zostáva spoľahlivý. Ak povinné kroky, predajné správy, definície, varovania a základné fakty všetky dostanú štýl poznámky, štítok prestáva pomáhať. Čitatelia musia preskúmať každý box, aby zistili, čo znamená, čo pridáva viac kognitívnej záťaže – duševného úsilia potrebného na spracovanie informácií – než by vytvoril obyčajný text.

Štítky závažnosti tiež učia správanie prostredníctvom opakovania. Keď neškodný kontext dostáva varovné farby, čitatelia opakovane narážajú na urgentný signál bez zmysluplného dôsledku. Učia sa ho prehliadať. Ďalšie skutočné varovanie potom súťaží s históriou falošných poplachov. Zneužívanie varovného štýlu pre poznámky nerobí len jednu stránku melodramatickou; oslabuje celý rizikový jazyk webu.

Pre stroje poskytuje typovaná poznámka explicitnú hranicu a účel. Nástroj na migráciu obsahu môže zachovať blok ako doplnkový kontext namiesto jeho zlúčenia do procedurálneho kroku. Vyhľadávací systém alebo AI agent môže extrahovať poznámku s jej štítkom a telom, potom ju udržať podriadenú tvrdeniu, ktoré vysvetľuje. Tento vzťah je ťažšie obnoviť z odseku zafarbeného na modro pomocou štýlu špecifického pre stránku.

Extrahovateľnosť stále závisí od písania. „Toto môže vyzerať inak“ nie je užitočné mimo svojho odseku, pretože chýba predmet. „Časové pečiatky správ používajú UTC, nie miestny čas diváka“ je sebestačné. Pravidlá písania prvkov majú prednosť: najprv klasifikujte pasáž podľa jej účelu, potom aplikujte registrovaný prvok. Vizuálne zvýraznenie nikdy nevytvára sémantický typ.

Kedy ho použiť

Použite poznámku len vtedy, keď sú splnené všetky štyri podmienky:

1. Pasáž objasňuje jedno blízke tvrdenie, hodnotu, inštrukciu, príklad alebo postupnosť.
2. Jej preskočenie nemení požadovanú činnosť, očakávaný výsledok, správnu interpretáciu hlavného tvrdenia ani úroveň rizika.
3. Kontext odpovedá na pravdepodobnú otázku čitateľa, ktorá by inak prerušila porozumenie.
4. Pasáž je dostatočne sebestačná na to, aby zostala zmysluplná pri extrakcii so svojím štítkom.

Dobrý materiál pre poznámku zahŕňa konvenciu časového pásma, alias názvu, hranicu rozsahu už implikovanú hlavným textom, neškodný rozdiel v rozhraní medzi verziami alebo vysvetlenie očakávaného stavu zobrazenia. Napríklad: „Tlačidlo je označené Uložiť na mesačných účtoch a Použiť na ročných účtoch; obe odosielajú rovnaké nastavenia.“ Činnosť a výsledok čitateľa sa nemenia.

Blízke zásahy sú dôležité, pretože „užitočná dodatočná informácia“ je príliš široká definícia:

• Fakt potrebný na pochopenie nasledujúceho odseku patrí do hlavného vysvetlenia. Skrytie v poznámke robí podstatné pochopenie voliteľným.
• Predpoklad patrí pred postup. Ak práca nemôže začať bez administrátorského prístupu, prístup nie je doplnkový kontext.
• Voliteľná technika, ktorá robí prácu rýchlejšou alebo lepšou, patrí do tip boxu . Tip mení kvalitu alebo efektivitu výsledku; poznámka nie.
• Podmienka, ktorá bráni vymazaniu, nákladom, expozícii, zraneniu alebo neplatnej práci, patrí do varovného boxu . Jej účelom je zmeniť správanie pred škodou.
• Formálna definícia, ktorá stanovuje, čo pojem znamená, patrí do definičného prvku alebo hlavného vysvetlenia, nie do poznámky.
• Citácia patrí vedľa tvrdenia, ktoré podporuje. Dôkaz nie je odbočka, keď na ňom tvrdenie závisí.
• Propagácia, výzva na registráciu alebo odporúčanie produktu je výzva na akciu, nie informácia.

Použite test žiadnej zmeny, keď si nie ste istí klasifikáciou: „Ak sa čitateľ dozvie túto skutočnosť, musí zmeniť činnosť, očakávanie, rozhodnutie alebo bezpečnostnú reakciu?“ Ak áno, nie je to poznámka. Ak nie, opýtajte sa, či daná skutočnosť rieši skutočnú nejednoznačnosť. Ak nie, vymažte ju alebo ju ponechajte ako obyčajný text namiesto vytvárania zvýraznenia.

Kam ju umiestniť

Umiestnite poznámku ihneď po kompletnom bloku obsahu, ktorý objasňuje. Cieľom môže byť odsek, položka zoznamu, krok, tabuľka, ukážka kódu alebo krátka postupnosť, ale cieľ musí dávať zmysel predtým, než sa poznámka objaví. Poznámka potom poskytuje doplnkový kontext bez rozdeľovania cieľa.

Keď sa poznámka vzťahuje na celú sekciu, umiestnite ju po úvodnom odseku, ktorý definuje rozsah sekcie. Tento rozsah pomenujte v prvej vete poznámky. Keď sa vzťahuje na postup, umiestnite ju po úvodnom odseku a pred prvý krok len vtedy, ak sa nemení žiadna činnosť; inak ide o predpoklad alebo varovanie. Poznámka o výstupe patrí po predstavení výstupu, nie o niekoľko odsekov neskôr.

Použite maximálne tri poznámky na stránku a jednu na sekciu. Tri sú strop. Ak sa viacero poznámok zhromažďuje okolo jednej pasáže, hlavný text pravdepodobne postráda vysvetlenie alebo materiál si zaslúži samostatnú podsekciu.

Poznámka nesmie byť umiestnená:

• Medzi nadpisom a jeho úvodným odsekom.
• Medzi tvrdením a dôkazom, ktorý ho podporuje.
• Medzi inštrukciou a požadovanou kontrolou úspechu.
• Priamo vedľa tipu, varovania, CTA, propagačného banneru alebo inej poznámky.
• Vo vnútri bunky tabuľky, odpovede FAQ, citácie, bloku kódu, akordeónového panelu alebo iného calloutu.
• V hrdinskom (hero) prvku len na vytvorenie vizuálneho záujmu, okrem prípadu, keď špecifikácia prvku vykresľuje jeho požadovaný živý príklad.
• Na konci stránky, keď sa jej cieľ objavil oveľa skôr.

Ak by susedstvo vytvorilo rad boxov, presuňte poznámku do textu alebo prestruktúrujte sekciu. Neriešte kolíziu zmenou poznámky na varovné farby; prezentácia nemôže opraviť nejasný vzťah obsahu.

Anatómia

Vykreslená poznámka má štyri viditeľné alebo štrukturálne oblasti:

1. Štítok typu: Viditeľné slovo „Poznámka“, ktoré identifikuje blok bez spoliehania sa na farbu alebo ikonu.
2. Voliteľný názov: Krátka, faktická fráza, ktorá pomenúva kontext, napríklad „Časové pásmo“ alebo „Štítky rozhrania“.
3. Telo: Jedno sebestačné objasnenie a, ak je to užitočné, veta, ktorá ho spája s blízkym obsahom.
4. Priľahlý cieľ: Kompletný blok alebo pomenovaná postupnosť, ktorá je objasňovaná. Umiestnenie nesie tento vzťah, hoci nejde o autorom písané textové pole.

Okraje, pozadia, ikony, medzery a typy písma patria do vykresľovača. Autori poskytujú význam, nie farebné inštrukcie alebo dekoratívne symboly.

Príklady dizajnu

Podporované varianty testujú obsah a responzívne správanie. Nevytvárajú rôzne úrovne dôležitosti.

Predvolené: Vykresľovač poskytuje „Poznámka“ a telo obsahuje jedno objasnenie. Používajte túto formu najčastejšie.

Vlastný názov: Faktický názov identifikuje tému. Nezvyšuje závažnosť ani nenahrádza sémantiku poznámky komponentu.

Maximálne dva odseky: Prvý odsek uvádza kontext; druhý rieši hranicu alebo neškodnú výnimku. Dlhšie vysvetlenia sa stávajú bežným obsahom.

Inline referencia: Jedna inline hodnota kódu alebo popisný odkaz môžu objasniť cieľ. Žiadna by nemala premeniť poznámku na dokumentáciu v rámci dokumentácie.

Úzky viewport: Štítok, názov a telo si zachovávajú svoje poradie čítania, bežne sa zalamujú a zostávajú zrozumiteľné bez okraja alebo ikony.

Parametre

Model obsahu oddeľuje pevný sémantický typ, voliteľné pomenovanie, telo a vzťah k blízkemu obsahu. „Zdroj“ hovorí, odkiaľ autor alebo vykresľovač získava hodnotu.

Názov je voliteľný, pretože „Poznámka“ je zvyčajne dostatočná. Prvý nadpis prenosnej direktívy sa môže mapovať na title podľa predvolených pravidiel tela, ale pre tento prvok je preferovaná stručná forma atribútu. Všetko ostatné sa mapuje na body. Súčasná Hugo implementácia akceptuje pozičný typ alebo pomenovaný type, plus voliteľný pomenovaný title; nikdy nemiešajte pozičné a pomenované parametre.

Syntax a príklady kódu

Tieto formy nesú rovnaký typ, názov a telo. Prezentácia na platforme sa môže líšiť, ale objasnenie musí zostať poznámkou.

Prenosná Markdown direktíva

:::note{title="Časové pásmo"}
Časové pečiatky správ používajú UTC. Filtre a výpočty sa nemenia, keď sa miestne časové pásmo diváka líši.
:::

Názov direktívy poskytuje typ, atribút poskytuje voliteľný názov a uzavretý Markdown poskytuje telo.

Hugo shortcode

{{< callout type="note" title="Time zone" >}}Report timestamps use UTC. Filters and calculations do not change when a viewer's local time zone differs.{{< /callout >}}

Tento príklad používa len pomenované parametre. Bez vlastného názvu je pozičná forma callout note platná a vykresľovač poskytuje štítok „Poznámka“.

WordPress blok alebo shortcode

<!-- wp:amicited/note {"title":"Časové pásmo"} -->
<p>Časové pečiatky správ používajú UTC. Filtre a výpočty sa nemenia, keď sa miestne časové pásmo diváka líši.</p>
<!-- /wp:amicited/note -->

[note title="Časové pásmo"]Časové pečiatky správ používajú UTC. Filtre a výpočty sa nemenia, keď sa miestne časové pásmo diváka líši.[/note]

Registrovaný blok je preferovaná WordPress implementácia. Shortcode je prijateľný, ak ho daná inštalácia explicitne podporuje; importné systémy nesmú sploštiť poznámku na varovanie ani odvodiť iný typ z jej farieb.

Príklady

Dobrý: neškodná variácia rozhrania

Toto je dobré, pretože odpovedá na pravdepodobnú otázku rozhrania pri zachovaní rovnakej činnosti a výsledku. Pomenúva oba štítky, hovorí, kde sa každý objavuje, a potvrdzuje ich ekvivalentné správanie. Poznámka dáva zmysel aj pri extrakcii z okolitého postupu.

Zlý: varovanie maskované ako informácia

Poznámka – Vymazanie pracovného priestoru: Vymazanie pracovného priestoru natrvalo odstráni jeho správy. Pred pokračovaním exportujte požadované záznamy.

Toto je zlé, pretože dôsledok vyžaduje zmenu správania pred nezvratnou akciou. Pokojné znenie a neutrálny štítok z toho nerobia doplnkový obsah. Musí to byť varovanie umiestnené pred ovládacím prvkom vymazania, s cieľom, dôsledkom a preventívnou akciou explicitne uvedenými.

Ďalšia zlá poznámka hovorí: „Export musí obsahovať všetky požadované stĺpce.“ To je akceptačné kritérium. Uveďte požadované stĺpce v inštrukcii alebo tabuľke špecifikácií. Tretia hovorí: „Môžete ušetriť čas filtrovaním exportu vopred.“ To je voliteľná rada zlepšujúca výsledok, a teda tip. Správna klasifikácia je dôležitejšia ako vizuálna rozmanitosť.

Schéma markup a prístupnosť

Poznámkový box nemá vyhradený typ alebo vlastnosť Schema.org. Zostáva viditeľným obsahom v rámci nadradeného Article, TechArticle, produktu alebo inej pravdivé schémy na úrovni stránky. Nevytvárajte preň samostatný JSON-LD objekt. Keď poznámka objasňuje krok, udržujte ju oddelenú od HowToStep.text, pokiaľ objasnenie nie je potrebné na vykonanie kroku; ak je potrebné, nešlo o voliteľný obsah poznámky.

Statická poznámka nepotrebuje role="alert", ARIA živú oblasť ani nútené oznámenie. Tieto mechanizmy komunikujú urgentnosť alebo dynamickú zmenu, zatiaľ čo poznámka je prítomná v normálnom poradí dokumentu a nesie neurgentný kontext. Agresívne oznámenie by nesprávne reprezentovalo jej dôležitosť a spôsobilo by hlučnejší výstup asistenčných technológií.

Vykreslite viditeľný štítok ako text v Document Object Model, nie ako obrázok na pozadí, tooltip len s ikonou alebo CSS-generovanú dekoráciu. Ak sa používa rola region, pripojte jej prístupný názov k viditeľnému štítku alebo vlastnému názvu. Poradie čítania je štítok, voliteľný názov, potom telo. Farba a ikony môžu typ posilniť, ale nemôžu byť jediným rozlíšením od tipov a varovaní.

Pri 200% zväčšení textu a na úzkom viewporte sa telo musí zalamovať bez horizontálneho posúvania. Odkazy vyžadujú popisný kotviaci text a musia byť prístupné z klávesnice. Inline kód musí zostať čitateľný pri vysokom kontraste. Podstatné informácie nemôžu existovať len v screenshotoch anatómie alebo v alternatívnom texte ikony.

Pravidlá písania

Cieľ 15 – 60 slov. Tvrdé maximum je 90 slov v maximálne dvoch krátkych odsekoch. Dlhšia pasáž si zvyčajne zaslúži integráciu do hlavného vysvetlenia; extrémne krátka poznámka je často štítok bez užitočného kontextu.

Napíšte jedno objasnenie na box v pokojnom, faktickom tóne. Uveďte predmet v prvej vete, potom vysvetlite neškodný rozdiel alebo hranicu. Uprednostnite presné formulácie ako „Časové pečiatky používajú UTC“ pred konverzačnou výplňou ako „Len aby ste vedeli.“ Uveďte dôvod pred akýmkoľvek interpretačným pravidlom: „Archivované projekty zostávajú viditeľné v historických správach, takže ich súčty sa môžu naďalej zobrazovať v minulých rozsahoch dátumov.“

Poznámka môže obsahovať obyčajné zvýraznenie, maximálne dve krátke inline hodnoty kódu a najviac jeden popisný odkaz. Nikdy nesmie obsahovať:

• Povinný krok, predpoklad, validačné pravidlo, kritérium úspechu alebo inštrukciu na obnovu.
• Materiálne riziko, nezvratný dôsledok, bezpečnostnú podmienku, právny pokyn alebo zverejnenie nákladov.
• Voliteľnú radu, ktorej účelom je zlepšiť rýchlosť, kvalitu, presnosť alebo pohodlie.
• Plnú definíciu, dôkaz potrebný na podporu tvrdenia alebo zoznam zdrojov.
• Viac ako jedno nezávislé objasnenie.
• Tabuľku, blok kódu, formulár, tlačidlo, CTA, referenciu, propagáciu alebo vnorený prvok.
• Vtipy, alarmistický jazyk, dekoratívne emoji alebo slová ako „kritické“ a „nebezpečenstvo.“

Nenazývajte každú poznámku „Dôležité.“ Dôležitosť nie je účelom prvku a slovo sa falošne približuje závažnosti varovania. Používajte „Poznámka“ alebo faktický názov témy. Nikdy nepoužívajte poznámku na záchranu nejasného textu: najprv opravte hlavné vysvetlenie, potom ponechajte poznámku len vtedy, ak naozaj zostáva doplnková nejednoznačnosť.

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

Frontmatter postTypes uvádza formáty, kde sa doplnkový kontext opakuje. Zaradenie je naďalej voliteľné; tabuľka definuje povolenú úlohu a pozíciu, nie povinné miesto.

Iné typy príspevkov môžu použiť poznámku, keď prejde rovnakým testom žiadnej zmeny. Uvedenie neospravedlňuje pridanie kvôli vizuálnemu rytmu a vynechanie nemení varovanie na poznámku.

Kontrolný zoznam QA

Pred publikovaním overte každú položku:

• Blok objasňuje jednu blízku pasáž a nemení činnosť, výsledok, prioritu, interpretáciu ani riziko.
• Kontext odpovedá na pravdepodobnú otázku čitateľa namiesto opakovania cieľa.
• Povinné informácie zostávajú v hlavnom obsahu.
• Poznámka je umiestnená ihneď po svojom kompletnom cieli alebo po odseku rozsahu pre pomenovanú postupnosť.
• Neoddeľuje nadpis od jeho úvodu, tvrdenie od dôkazu ani inštrukciu od kontroly úspechu.
• Priamo vedľa nej nie je varovanie, tip, CTA, banner ani druhá poznámka.
• Stránka nemá viac ako tri poznámky a sekcia nemá viac ako jednu.
• Telo má 15 – 60 slov, zostáva pod 90 slovami a obsahuje jedno objasnenie.
• Viditeľný textový štítok funguje bez farby, okraja, ikony alebo obrázka.
• Text zostáva zmysluplný pri extrakcii so štítkom, ale bez okolitého stylovania.
• Box nepoužíva rolu alert ani živú oblasť, keď je prítomný pri načítaní stránky.
• Mapovania v Markdown, Hugo a WordPress zachovávajú typ, názov, telo a umiestnenie.
• Hugo parametre sú výhradne pozičné alebo výhradne pomenované; nikdy nie sú zmiešané.
• Vo vnútri nie je žiadny nepodporovaný vnorený komponent, blok kódu, tabuľka, formulár ani propagačná akcia.
• Značky screenshotov požadujú budúce zachytenie bez vykresľovania neexistujúcich aktív.

FAQ

Aký je rozdiel medzi poznámkou, tipom a varovaním? Poznámka objasňuje bez toho, aby čokoľvek menila. Tip ponúka voliteľné zlepšenie. Varovanie mení správanie, aby sa predišlo škode, strate, nákladom, expozícii alebo neplatnej práci. Klasifikujte podľa dôsledku preskočenia bloku, nie podľa jeho farby.

Môže poznámkový box obsahovať povinné informácie? Nie. Povinné informácie patria do hlavného obsahu, kde sa s nimi každý čitateľ stretne v poradí. Poznámka môže vysvetliť neškodnú variáciu, ale jej preskočenie nemôže spôsobiť nesprávnu úlohu alebo interpretáciu.

Koľko poznámkových boxov by mala stránka obsahovať? Použite maximálne tri na stránku a jednu na sekciu. Väčšina stránok potrebuje menej. Opakované poznámky naznačujú, že hlavné vysvetlenie potrebuje prestavbu.

Má poznámkový box používať varovné farby alebo rolu alert? Nie. Varovná prezentácia signalizuje materiálny dôsledok a role="alert" signalizuje urgentné dynamické informácie. Použitie ktoréhokoľvek z nich na bežný kontext učí ľudí ignorovať skutočný signál a zavádza používateľov asistenčných technológií.

Môže poznámkový box obsahovať odkazy alebo kód? Môže obsahovať jeden popisný odkaz alebo maximálne dve krátke inline hodnoty kódu, ak priamo objasňujú cieľ. Pre bloky kódu, tabuľky, formuláre alebo viackrokovú dokumentáciu použite hlavný obsah.

Poznámka si zaslúži svoju hranicu tým, že rieši skutočnú nejednoznačnosť, pričom ponecháva kurz čitateľa nezmenený. Udržujte ju pokojnú, priľahlú, sebestačnú a vizuálne odlišnú od rád a rizík.