DevSite podporuje niekoľko štýlov upozornení prezentovaných ako rámčeky s rôznymi farbami pozadia. Farby pozadia sú preddefinované a môžete vytvárať upozornenia pomocou HTML alebo Markdown.
Dostupné typy upozornení
Poznámka
HTML
<aside class="note">
<b>Note:</b> An ordinary note.
</aside>
Markdown
Note: An ordinary note.
Tip
HTML
<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>
Markdown
Tip: An ordinary tip.
Pozor
HTML
<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>
Markdown
Caution: Suggests proceeding with caution.
POZOR
HTML
<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>
Markdown
Warning: Stronger than caution; it means "Don't do this."
Dôležité
HTML
<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>
Markdown
Important: Defines an important concept.
Kľúčový bod
HTML
<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>
Markdown
Key Point: Defines an important takeaway.
Kľúčový termín
HTML
<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>
Markdown
Key Term: Defines important terminology.
Cieľ
HTML
<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>
Markdown
Objective: Defines the goal of a procedure.
Úspech
HTML
<aside class="success">
<b>Success:</b> Describes a successful action or an error-free status.
Used only in interactive or dynamic content; don't use in ordinary
static pages.
</aside>
Markdown
Success: Describes a successful action or an error-free status. Used only
in interactive or dynamic content; don't use in ordinary static pages.
Beta
HTML
<aside class="beta">
<b>Beta:</b> A notice that describes a beta-release feature, which is
subject to change or removal in new minor versions of the product.
</aside>
Markdown
Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.
Ukážka
HTML
<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>
Markdown
Preview: A note or tip for a feature preview.
Interné testovanie
HTML
<aside class="dogfood">
<b>Dogfood:</b> A notice that applies only temporarily, during internal
dogfood testing. Remove all Dogfood notices before making a document
publicly visible.
</aside>
Markdown
Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.
Zastarané
HTML
<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>
Markdown
Deprecated: A note or tip for a deprecated feature, product, or service.
Poznámky k použitiu
Použitie HTML
Odporúčame používať tieto triedy s prvkom HTML5 <aside> , ale namiesto toho môžete použiť iný prvok na úrovni bloku (napríklad <p> ).
Triedy HTML určujú farbu a ikonu oznámenia, ale nenastavujú automaticky prvé slovo tučné; toto slovo musíte napísať ručne, ako je znázornené v príkladoch. Teoreticky by ste mohli použiť aj iné slovo ako to, ktoré zodpovedá triede, ale odporúčame vám zostať pri prvých slovách uvedených vyššie.
V starších dokumentoch môžete vidieť class="special" alebo neštandardné názvy tried namiesto class="note" . Tieto názvy tried vytvárajú oznámenia, ktoré sú vizuálne identické s note , ale namiesto špeciálnych alebo neštandardných názvov tried odporúčame použiť class="note" .
Použitie markdown
Štýly Markdown určujú farbu a ikonu oznámenia a automaticky nastavujú prvé slovo oznámenia tučné. Takže napríklad poznámka v Markdown vždy začína slovom Note: tučným písmom.
Pre oznámenie s viac ako jedným odsekom použite namiesto toho HTML <aside> (a <p> ).
Môže sa vám zobraziť Dôležité: namiesto Note: . Tento štýl Markdown vytvára oznámenia, ktoré sú vizuálne identické s oznámením Note: :.
Osvedčené postupy
DevSite odporúča, aby ste pri pridávaní upozornení do dokumentácie dodržiavali nasledujúce osvedčené postupy:
Odporúčané
- Buďte struční (snažte sa dodržať upozornenia na jednu alebo dve vety).
- Ak je to možné, obmedzte upozornenia na jedno na stránku (alebo v prípade potreby jedno na sekciu).
- Uistite sa, že oznámenia obsahujú iba dôležitý obsah, ktorý chcete zdôrazniť; nezahŕňajte do oznámenia obsah, s ktorým si jednoducho nie ste istí, čo robiť.
- Používajte upozornenia skôr, ako používateľ potrebuje informácie, nie potom.
Neodporúča sa
- Do upozornení neuvádzajte príklady kódu, tabuľky ani obrázky.
- Vyhnite sa ukladaniu oznámení na seba, aj keď sú rôzneho typu.
- Snažte sa nevkladať upozornenia hneď za nadpisy.
- Nepoužívajte upozornenia na špecifikovanie predpokladov pred procedúrou.
Z väčšej časti sa tieto osvedčené postupy vzťahujú na upozornenia typu note , caution a warning , ale môžu sa vzťahovať aj na iné typy.
Dobré príklady
Jednoducho:
Dávajte cautions na možnú stratu údajov:
Použite warning pred možným zranením:
Použite vhodné typy upozornení pre obsah, ako je key-term alebo success :
Zlé príklady
Oznámenia by nemali byť príliš podrobné a nemali by poskytovať informácie, ktoré patria do základného obsahu:
Oznámenia by nemali špecifikovať predpoklady pred postupom (namiesto toho použite sekciu „Prerekvizity“):