Definicja (Definition Box): Format, zasady i przykłady

Definition box nadaje głównemu terminowi strony jedno precyzyjne, zamknięte wyjaśnienie, zanim artykuł go rozwinie. Jest to element otwierający: wielokrotnego użytku komponent treści, który pojawia się blisko początku, ponieważ czytelnik nie powinien musieć wnioskować o głównym terminie z przykładów, korzyści czy kontekstu.

Ten żywy przykład to kompletny element, a nie zapowiedź definicji umieszczonej dalej na stronie. Jego tytuł jest opcjonalny; treść już nie. Poniższy kontrakt produkcyjny określa, kiedy element ma zastosowanie, co oznacza każde pole i jak ta sama treść jest mapowana w różnych systemach publikacji.

Dlaczego ten element jest ważny

Czytelnicy rzadko zaczynają czytanie strony informacyjnej od każdego słowa po kolei. Skanują tytuł, pierwsze linijki, nagłówki i wizualnie wyróżnione bloki, aby zdecydować, czy strona odpowiada na ich pytanie. Definicja ukryta w akapicie wprowadzającym zmusza czytelnika do oddzielenia odpowiedzi od kontekstu, twierdzeń i wprowadzenia w temat. Box usuwa tę pracę: jego granica mówi „to jest definicja".

Ta granica nadaje również definicji stabilną, adresowalną pozycję. Redaktorzy wiedzą, gdzie ją sprawdzić, szablony wiedzą, gdzie ją wyrenderować, a przyszłe zmiany nie zmuszają czytelnika ani osoby kontrolującej jakość do przeszukiwania kilku akapitów otwierających. Spójne umiejscowienie ma znaczenie w całej bibliotece, ponieważ to samo zadanie informacyjne nie powinno przesuwać się w nieprzewidywalny sposób między stronami.

Wyodrębnialność maszynowa to zdolność oprogramowania do wyizolowania jednostki treści bez utraty jej znaczenia. Typowana definicja z tytułem i treścią może być indeksowana, porównywana, cytowana lub przekształcana niezależnie. Zdanie, które jedynie przypadkiem definiuje termin w ramach dowolnego tekstu, rozpływa się w otaczającej prozie: oprogramowanie musi zgadywać, gdzie definicja się zaczyna, gdzie kończy i czy poprzedzające twierdzenie jest jej częścią. Postępuj zgodnie z zasadami pisania elementów , aby tożsamość semantyczna przetrwała nawet wtedy, gdy zmieni się wygląd wizualny.

Sformułowanie musi jednak działać również bez boxa. Stylizacja tworzy kontrast dla ludzi; samodzielny podmiot, orzeczenie i wyróżniające znaczenie tworzą wyodrębnialność dla maszyn. „Jest to metoda ich ulepszania” nie działa po wyjęciu z akapitu. „Czyszczenie treści (content pruning) to proces usuwania, konsolidowania lub aktualizowania stron, które nie służą już użytecznemu celowi wyszukiwania lub biznesowemu” — działa.

Kiedy go używać

Używaj definition box, gdy strona jest zorganizowana wokół jednego terminu i termin ten można precyzyjnie zdefiniować w krótkim stwierdzeniu. Jest obowiązkowy dla formatów hasła słownikowego (glossary-term) i co-to-jest-X. Jest również obowiązkowy w treściach o charakterze diagnostycznym lub dotyczących schorzeń: czytelnik musi wiedzieć, czym jest nazwane schorzenie, zanim rozważy przyczyny, testy lub sposoby leczenia.

Strony prowadzone od objawów oraz poradniki instruktażowe używają tego elementu rzadko. Dodawaj go tylko wtedy, gdy jedna krótka definicja rozwiewa autentyczną niejednoznaczność niezbędną do wykonania zadania. Na przykład poradnik zatytułowany „Jak naprawić kanibalizację słów kluczowych” może zdefiniować kanibalizację słów kluczowych przed krokami postępowania, ponieważ diagnoza decyduje o tym, które rozwiązanie ma zastosowanie. Poradnik zatytułowany „Jak zmienić tag title” nie potrzebuje boxa definiującego tag title, jeśli odbiorcy i polecenie otwierające już jednoznacznie określają obiekt.

Nie używaj definition box do:

• Szerokiego wprowadzenia, historii, przedstawienia korzyści lub wyjaśnienia, dlaczego dany temat jest ważny. Te fragmenty rozwijają artykuł; nie definiują terminu.
• Podsumowania strony. Podsumowanie zbiera kilka wniosków, podczas gdy definicja podaje znaczenie jednego terminu.
• Obietnicy produktowej, np. „AmICited to najłatwiejszy sposób na poprawę widoczności”. To pozycjonowanie, a nie weryfikowalna definicja.
• Ostrzeżenia, zastrzeżenia, wymagania wstępnego ani wskazówki. Ich zadanie komunikacyjne jest inne, nawet jeśli tematyka mogłaby sprawić, że wyglądałyby jak ten sam kolorowy panel.
• Terminu pobocznego wprowadzonego w środku artykułu. Zdefiniuj ten termin w zdaniu, w którym pojawia się po raz pierwszy, lub daj mu własną stronę, jeśli zasługuje na szersze omówienie.
• Cytatu, którego autorytet zastępuje jasność. Przypisz formalną definicję w otaczającej prozie, gdy atrybucja jest konieczna; zachowaj box czytelny jako bezpośrednie stwierdzenie.

Częstym chybionym podejściem jest „wprowadzenie do definicji": „Churn klientów to jedna z najważniejszych koncepcji dla firm subskrypcyjnych, a jej zrozumienie może przekształcić rozwój". Mówi to, że koncepcja jest ważna, ale nigdy nie mówi, czym jest. Box nie może nadać precyzji pustemu wprowadzeniu w temat.

Gdzie go umieścić

Umiejscowienie koduje priorytet. Umieść definition box bezpośrednio po akapicie wprowadzającym lub krótkim wprowadzeniu, jako pierwszy blok treści. Wprowadzenie wyjaśnia, dlaczego czytelnik trafił na stronę; box następnie ustala znaczenie, zanim przyczyny, przykłady, korzyści, kroki lub porównania będą od niego zależeć.

Nie umieszczaj nawigacji, spisu treści, kluczowych wniosków, galerii zdjęć ani wezwania do działania o charakterze promocyjnym między wprowadzeniem a definicją. Te bloki zmuszają czytelnika do przejścia przez niezwiązane materiały przed poznaniem znaczenia terminu. Breadcrumbs i hero strony to elementy szablonu, a nie autorska treść, więc mogą poprzedzać wprowadzenie.

Używaj jednego definition box na stronę. Zasada istnieje, ponieważ komponent identyfikuje główny obiekt definicyjny strony. Dwa boxy tworzą dwa konkurujące główne terminy i powodują niejednoznaczność wyodrębniania. Jeśli oba terminy są rzeczywiście główne, podziel temat na dwie strony i połącz je w prozie. Jeśli drugi termin jest podrzędny, zdefiniuj go w tekście, zamiast stylizować go jako drugą kanoniczną odpowiedź.

Blok bezpośredniej odpowiedzi może współistnieć z definicją tylko wtedy, gdy odpowiada na inne główne pytanie. Na stronie diagnostycznej definicja może stwierdzać, czym jest schorzenie, podczas gdy blok bezpośredniej odpowiedzi podaje zalecane pierwsze działanie. Gdy główne pytanie strony brzmi „Co to jest X?”, blok bezpośredniej odpowiedzi i definicja są tą samą odpowiedzią. Połącz je w jeden definition box; sąsiednie wersje jedynie powtarzają sformułowania i konkurują o wyodrębnienie.

Anatomia

Element ma dwa obszary autorskie i jedną relację strukturalną. Zrzut ekranu musi pokazywać wyrenderowany element bez wbudowywania tekstu wyjaśniającego w obraz; legenda poniżej pozostaje wybieralna, dostępna i łatwa w utrzymaniu przy zmianie wyglądu.

Legenda renderowana

1. Opcjonalny tytuł: Zazwyczaj „Co to jest X?". Identyfikuje dokładny termin i nie może dodawać drugiego twierdzenia.
2. Wymagana treść: Jedna samodzielna definicja, która podaje nazwę terminu, umieszcza go w użytecznej kategorii i określa, co go wyróżnia.
3. Pozycja otwierająca: Box następuje po wprowadzeniu i poprzedza pierwszą sekcję wyjaśniającą. Ta relacja jest częścią kontraktu, nawet jeśli nie jest polem.

Obramowanie, tło, dopełnienie, ikona i typografia należą do mechanizmu renderującego. Autorzy dostarczają znaczenie, a nie elementy wizualne. Element musi pozostać zrozumiały po usunięciu wszystkich dekoracji stylistycznych.

Przykłady projektowe

Galeria obejmuje obsługiwane warianty treści, a nie wymyśla różne typy semantyczne. Każde ujęcie powinno tam, gdzie to możliwe, wykorzystywać tę samą definicję, aby recenzenci mogli ocenić obsługę tytułu, zawijanie treści i zachowanie w różnych widokach, zamiast porównywać niepowiązane teksty.

Z tytułem: Preferowany wariant, gdy termin jest nieznany, niejednoznaczny, skrócony lub różni się od dokładnego tytułu strony.

Bez tytułu: Dozwolone, gdy nagłówek strony i bezpośrednio poprzedzające wprowadzenie jednoznacznie określają temat. Treść musi jednak nadal zawierać nazwę terminu; pominięcie tytułu nigdy nie zezwala na używanie zaimków takich jak „to" w miejsce podmiotu.

Maksymalna długość: Mechanizm renderujący zawija całą treść. Nie może jej obcinać, zwijać, przewijać ani zmniejszać czcionki, aby dopasować się do treści o maksymalnej dopuszczalnej długości redakcyjnej.

Wąski widok: Tytuł i treść zachowują swoją kolejność, czytelną długość wiersza i widoczną granicę. Żadne znaczenie nie może zależeć od ikony przesuniętej obok tekstu.

Parametry

Parametry oddzielają treść od prezentacji. Ich ograniczenia zapewniają porównywalność definicji między stronami i uniemożliwiają przekształcenie komponentu w ogólnego callouta.

Parametry definition box

Mechanizm renderujący może wyprowadzać termin do celów indeksowania, ale autorzy nigdy nie powinni pisać treści zależnej od wyświetlania tego wyprowadzonego pola. Skopiowana definicja musi wyraźnie podawać swój podmiot.

Składnia i przykłady kodu

Wszystkie trzy formy niosą ten sam tytuł i treść. Przenośna dyrektywa Markdown jest kanoniczną formą autorską; Hugo i WordPress są adapterami. Przykłady celowo używają identycznych sformułowań, aby test migracji mógł porównać wartości, a nie tylko wygląd.

Przenośna dyrektywa Markdown

:::definition
## Co to jest czyszczenie treści?

Czyszczenie treści (content pruning) to proces usuwania, konsolidowania lub aktualizowania stron, które nie służą już użytecznemu celowi wyszukiwania lub biznesowemu.
:::

Pierwszy nagłówek mapuje się na title; wszystko po nim mapuje się na body. Pomiń nagłówek w wariancie bez tytułu, ale zachowaj termin w treści.

Shortcode Hugo

{{< callout type="note" title="Co to jest czyszczenie treści?" >}}Czyszczenie treści (content pruning) to proces usuwania, konsolidowania lub aktualizowania stron, które nie służą już użytecznemu celowi wyszukiwania lub biznesowemu.{{< /callout >}}

Strona wykorzystuje istniejący renderer callout dla widocznego przetwarzania Hugo. Kontrakt definicji nadal pochodzi z typowanego przenośnego źródła: note jest tutaj adapterem renderowania, a nie pozwoleniem na umieszczanie zwykłych notatek w definition boxach.

Blok lub shortcode WordPress

[definition title="Co to jest czyszczenie treści?"]Czyszczenie treści (content pruning) to proces usuwania, konsolidowania lub aktualizowania stron, które nie służą już użytecznemu celowi wyszukiwania lub biznesowemu.[/definition]

Implementacja w WordPress może udostępniać te same pola jako niestandardowy blok. Przechowywane wartości pozostają title i body; elementy sterujące edytora, kolory i odstępy są ustawieniami prezentacji i nie mogą zmieniać znaczenia definicji.

Przykłady

To jest dobry przykład, ponieważ podaje nazwę terminu, identyfikuje warunek i określa wyróżniającą konsekwencję. Nie twierdzi, że każda para stron dzielących słowo konkuruje; sformułowanie „ta sama intencja wyszukiwania" zapewnia niezbędną granicę. Treść jest użyteczna bez tytułu i wystarczająco krótka, aby zacytować ją w całości.

To jest zły przykład, ponieważ nigdy nie definiuje kanibalizacji słów kluczowych. Oferuje ważność, odbiorców, pilność i niejasny efekt, ale brakuje kategorii lub warunku odróżniającego. Zastąpienie „jednego z najważniejszych" przez „sytuację, w której wiele stron konkuruje o tę samą intencję wyszukiwania" zamienia promocję w znaczenie.

Drugim złym wzorcem jest przeciążenie boxa: definicja, po której następują przyczyny, pięć przykładów, ostrzeżenie i zalecane narzędzie. Nawet jeśli pierwsze zdanie jest poprawne, dodatkowy materiał niszczy stabilną granicę. Zachowaj definicję; przenieś przyczyny i przykłady do następnej sekcji, ostrzeżenie do odpowiedniego elementu, a zalecenie do miejsca, w którym czytelnik może na nim działać.

Znaczniki schema i dostępność

Definition box nie tworzy automatycznie samodzielnego bytu Schema.org. W zwykłym artykule jego tekst pozostaje częścią otaczającego Article lub TechArticle. Na stronie słownikowej implementacja publikacyjna może mapować termin i definicję do odpowiedniego słownictwa tylko wtedy, gdy witryna przyjęła taką politykę dotyczącą schema. Nie wymyślaj typu DefinitionBox: nie istnieje on w Schema.org.

Podobnie, nie duplikuj treści w JSON-LD tylko dlatego, że box wygląda na ważny. Znaczniki schema muszą opisywać stronę zgodnie z prawdą, a powielanie widocznej prozy w niepowiązanej właściwości tworzy szum, a nie silniejsze znaczenie. Jeśli jakaś właściwość schema jest wypełniona, jej wartość musi odpowiadać widocznej definicji pod względem treści i być z nią aktualizowana.

Element nie potrzebuje interaktywnej roli ARIA. Renderuj go w normalnej kolejności dokumentu jako oznaczony region lub kontener semantyczny, z tytułem przed treścią. Nie używaj role="alert", ponieważ statyczna definicja nie jest pilną ani nowo pojawiającą się informacją. Nie używaj koloru ani ikony jako jedynego sygnału, że blok jest definicją. Jeśli tytuł jest zaimplementowany jako nagłówek, jego poziom musi być zgodny z hierarchią strony; ## w źródle to konwencja mapowania pól, a nie instrukcja tworzenia nieprawidłowego skoku nagłówka.

Zachowanie klawiaturowe to zwykłe zachowanie czytelnicze: sam box nie jest elementem skupialnym. Wszelkie linki wewnątrz podlegają zwykłej semantyce linków i wymagają opisowej kotwicy. Wyjście czytnika ekranu musi zachowywać tę samą kolejność tytuł-następnie-treść, która jest widoczna na ekranie.

Zasady pisania

Napisz definicję przed napisaniem jej korzyści. Zacznij od samego terminu, a następnie użyj czasownika łącznikowego, takiego jak „jest", „oznacza" lub „występuje, gdy". Podaj najbliższą użyteczną kategorię oraz cechę odróżniającą termin od pokrewnych pojęć. Ta sekwencja istnieje, ponieważ kategoria bez rozróżnienia jest zbyt ogólna, podczas gdy rozróżnienie bez kategorii pozostawia czytelnika niepewnym, jakiego rodzaju rzeczą jest termin.

Zachowaj treść na maksymalnie około 300 znaków, wliczając spacje. Preferuj jedno zdanie. Drugie krótkie zdanie jest dopuszczalne tylko wtedy, gdy niezbędna granica nie może być wyraźnie przedstawiona w pierwszym. Limit ma charakter redakcyjny, a nie jest zaproszeniem do kompresowania interpunkcji, usuwania rodzajników czy piętrzenia zdań podrzędnych. Jeśli dokładność wymaga więcej miejsca, umieść dokładny rdzeń w boxie i uzupełnij go bezpośrednio po nim.

Używaj neutralnego, oznajmującego tonu. Unikaj „ważny", „potężny", „rewolucyjny", „musisz wiedzieć" i podobnych osądów. Unikaj definicji cyrkularnych, takich jak „optymalizacja treści to akt optymalizacji treści". Rozwijaj skróty przy pierwszym użyciu, chyba że sam skrót jest terminem strony. Używaj tej samej kanonicznej nazwy, która występuje w tytule strony.

Nigdy nie umieszczaj w treści:

• Więcej niż jednego głównego terminu ani listy powiązanych terminów.
• Korzyści, historii, przyczyn, objawów, przykładów, kroków, ofert produktowych ani wezwań do działania.
• Tabel, obrazów, filmów, formularzy, przycisków, przypisów dolnych ani zagnieżdżonych calloutów.
• Niepopartych superlatywów, zmyślonych statystyk ani twierdzeń wymagających akapitu dowodów.
• Drugiego nagłówka, listy punktowanej ani blokowego cytatu.
• Zaimków, których znaczenie zależy od poprzedzającego wprowadzenia.

Jeden link atrybucyjny jest wyjątkiem, a nie celem. Używaj go tylko wtedy, gdy definicja prawna, naukowa lub oparta na standardach zależy od nazwanego źródła. Rozszerzone cytowania i rozbieżności między źródłami umieszczaj w zwykłej prozie, gdzie czytelnik może zobaczyć zastrzeżenia, zamiast mylić jedno sporne sformułowanie z uniwersalną definicją.

Typy stron, które go używają

Front matter postTypes rejestruje zatwierdzone powiązania. Poniższa tabela przekłada te powiązania na zasady redakcyjne. Formaty diagnostyczne/chorobowe i oparte na objawach są opisane tutaj jako wzorce użycia, ale nie są linkowane jako osobne typy stron w playbooku, ponieważ nie znajdują się w bieżącym kanonicznym rejestrze.

Wymagania według typu strony

W przypadku stron o charakterze diagnostycznym lub dotyczących schorzeń używaj boxa zawsze i umieszczaj go przed objawami, przyczynami, stopniem nasilenia lub sposobami leczenia. W przypadku stron prowadzonych od objawów używaj go tylko wtedy, gdy nazwa objawu ma rzeczywiście krótką, stabilną definicję. Jeśli box jedynie powtarzałby tytuł – „Wolna strona internetowa to strona internetowa, która jest wolna" – pomiń go i zacznij od prozatorskiego opisu progu diagnostycznego lub obserwowalnego problemu.

Lista kontrolna QA

Osoba recenzująca sprawdza znaczenie przed wyglądem. Dopracowany box zawierający niejasne wprowadzenie to wciąż nieudana definicja.

• Jeden główny termin: Strona i box definiują dokładnie jedną główną koncepcję.
• Prawidłowa pozycja: Box jest pierwszym autorskim blokiem treści po wprowadzeniu, bez wstawionego przed nim spisu treści, wniosków, galerii ani promocji.
• Jedno wystąpienie: Żaden drugi definition box nie konkuruje z kanoniczną odpowiedzią.
• Rzeczywista definicja: Treść określa, czym jest termin lub kiedy istnieje dany warunek; nie mówi jedynie, dlaczego termin jest ważny.
• Samodzielne sformułowanie: Treść podaje swój podmiot i ma sens po skopiowaniu bez otaczającej prozy lub stylizacji.
• Precyzja: Kategoria, cecha wyróżniająca i wszelkie istotne granice są dokładne. Sformułowanie nie jest zbyt ogólne.
• Długość: Treść liczy nie więcej niż około 300 znaków i pozostaje czytelna, a nie skompresowana.
• Czysta zawartość: Wewnątrz nie ma korzyści, historii, przykładów, kroków, ofert produktowych, multimediów, tabel ani zagnieżdżonych elementów.
• Decyzja o bezpośredniej odpowiedzi: Jeśli strona zadaje pytanie „Co to jest X?", definition box jest jedynym elementem bezpośredniej odpowiedzi. Jeśli oba elementy występują, odpowiadają na wyraźnie różne pytania.
• Dostępna semantyka: Tytuł poprzedza treść, kolejność nagłówków jest prawidłowa, kolor nie jest jedynym identyfikatorem i nie występuje rola alertu ani niepotrzebny cel fokusu.
• Przenośna parytet: Mapowania w Markdown, Hugo i WordPress zachowują ten sam tytuł i definicję.
• Powściągliwość w danych strukturalnych: Każda wartość schema jest zgodna z widocznym tekstem i nie użyto wymyślonego typu Schema.org.
• Status zrzutów ekranu: Komentarze pozostają instrukcjami przechwytywania (nie do renderowania), dopóki nazwane pliki nie istnieją; żadna nieistniejąca ścieżka obrazu nie jest przywoływana jako obraz.

FAQ

Szablon academy renderuje pięć przeanalizowanych pytań przechowywanych w front matter [[faq]] tej strony. Obejmują one konieczność, współistnienie z bezpośrednimi odpowiedziami, linki i cytowania, limit długości oraz zasadę jednego boxa na stronę.