Upozornění (popisky, poznámky, varování atd.)

DevSite podporuje několik stylů oznámení prezentovaných jako rámečky s různými barvami pozadí. Barvy pozadí jsou předdefinované a můžete vytvářet upozornění pomocí HTML nebo Markdown.

Dostupné typy oznámení

Poznámka

<aside class="note">
<b>Note:</b> An ordinary note.
</aside>

Note: An ordinary note.

Tip

<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>

Tip: An ordinary tip.

Pozor

<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>

Caution: Suggests proceeding with caution.

Varování

<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>

Warning: Stronger than caution; it means "Don't do this."

Důležité

<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>

Important: Defines an important concept.

Klíčový bod

<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>

Key Point: Defines an important takeaway.

Klíčový termín

<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>

Key Term: Defines important terminology.

Objektivní

<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>

Objective: Defines the goal of a procedure.

Úspěch

<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>

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

<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>

Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.

Náhled

<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>

Preview: A note or tip for a feature preview.

Interní test

<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>

Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.

Zastaralé

<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>

Deprecated: A note or tip for a deprecated feature, product, or service.

Poznámky k použití

Použití HTML

Tyto třídy doporučujeme používat s prvkem HTML5 <aside> , ale můžete místo toho použít jiný prvek na úrovni bloku (například <p> ).

Třídy HTML určují barvu a ikonu oznámení, ale nenastavují automaticky první tučné slovo; musíte toto slovo napsat ručně, jak je znázorněno v příkladech. Teoreticky byste mohli použít i jiné slovo než to, které odpovídá třídě, ale doporučujeme, abyste zůstali u prvních slov uvedených výše.

Ve starších dokumentech můžete místo class="note" vidět class="special" nebo nestandardní názvy tříd. Tyto názvy tříd vytvářejí upozornění, která jsou vizuálně identická s upozorněním note , ale místo speciálních nebo nestandardních názvů tříd doporučujeme použít class="note" .

Použití markdown

Styly Markdown určují barvu a ikonu upozornění a automaticky nastavují první slovo upozornění tučně. Takže například poznámka v Markdown vždy začíná slovem Note: tučně.

Pro oznámení s více než jedním odstavcem použijte místo toho HTML <aside> (a <p> ).

Může se vám zobrazit Důležité: místo Note: . Tento styl Markdown vytváří upozornění, která jsou vizuálně identická s Note: Note:.

Nejlepší postupy

DevSite doporučuje, abyste při přidávání upozornění do dokumentace dodržovali následující doporučené postupy:

Doporučeno

• Buďte struční (snažte se dodržet upozornění na jednu nebo dvě věty).
• Pokud je to možné, omezte oznámení na jedno na stránku (nebo v případě potřeby jedno na sekci).
• Ujistěte se, že oznámení obsahují pouze důležitý obsah, který chcete zvýraznit; nezahrnujte do oznámení obsah, u kterého si prostě nejste jisti, co dělat.
• Používejte upozornění předtím, než uživatel potřebuje informace, nikoli poté.

Nedoporučuje se

• Do upozornění neuvádějte příklady kódu, tabulky ani obrázky.
• Vyhněte se skládání oznámení na sebe, i když jsou různého typu.
• Snažte se nevkládat upozornění bezprostředně za nadpisy.
• Nepoužívejte upozornění ke specifikaci předpokladů před procedurou.

Z větší části se tyto osvědčené postupy vztahují na upozornění typu note , caution a warning , ale mohou se vztahovat i na jiné typy.

Dobré příklady

Jednoduše:

Dejte si cautions na potenciální ztrátu dat:

Použijte warning před možným zraněním:

Používejte vhodné typy oznámení pro obsah, jako je key-term nebo success :

Špatné příklady

Oznámení by neměla být příliš podrobná a neměla by obsahovat informace, které patří do hlavního obsahu:

Oznámení by neměla specifikovat předpoklady před procedurou (místo toho použijte sekci "Předpoklady"):