Obvestila (oblački, opombe, opozorila itd.)

DevSite podpira več slogov obvestil, predstavljenih kot polja z različnimi barvami ozadja. Barve ozadja so vnaprej določene, obvestila pa lahko ustvarite s HTML ali Markdown.

Razpoložljive vrste obvestil

Opomba

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

Note: An ordinary note.

Namig

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

Tip: An ordinary tip.

Previdnost

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

Caution: Suggests proceeding with caution.

Opozorilo

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

Pomembno

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

Important: Defines an important concept.

Ključna točka

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

Key Point: Defines an important takeaway.

Ključni izraz

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

Key Term: Defines important terminology.

Cilj

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

Objective: Defines the goal of a procedure.

Uspeh

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

Predogled

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

Preview: A note or tip for a feature preview.

Dogfood

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

Zastarelo

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

Opombe o uporabi

uporaba HTML

Priporočamo uporabo teh razredov z elementom HTML5 <aside> , vendar lahko namesto tega uporabite drug element na ravni bloka (kot je <p> ).

Razredi HTML določajo barvo in ikono obvestila, vendar ne nastavijo samodejno krepke prve besede; to besedo morate napisati ročno, kot je prikazano v primerih. Teoretično bi lahko uporabili besedo, ki ni tista, ki ustreza razredu, vendar priporočamo, da se držite prvih zgoraj prikazanih besed.

V starejših dokumentih boste morda videli class="special" ali nestandardna imena razredov namesto class="note" . Ta imena razredov ustvarijo obvestila, ki so vizualno enaka note , vendar priporočamo uporabo class="note" namesto posebnih ali nestandardnih imen razredov.

Markdown uporaba

Slogi Markdown določajo barvo in ikono obvestila ter samodejno nastavijo krepko prvo besedo obvestila. Tako se na primer opomba v Markdown vedno začne z besedo Note: v krepkem tisku.

Za obvestilo z več kot enim odstavkom namesto tega uporabite HTML <aside> (in <p> ).

Morda boste videli Pomembno: namesto Note: . Ta slog Markdown ustvari obvestila, ki so vizualno enaka obvestilu Note: :.

Najboljše prakse

DevSite priporoča, da pri dodajanju obvestil v svojo dokumentacijo upoštevate naslednje najboljše prakse:

Priporočeno

• Bodite jedrnati (poskusite obdržati obvestila v enem ali dveh stavkih).
• Omejite obvestila na eno na stran, če je mogoče (ali eno na razdelek, če je potrebno).
• Zagotovite, da obvestila vsebujejo samo pomembno vsebino, ki jo želite izpostaviti; v obvestilo ne vključujte vsebine, s katero preprosto niste prepričani, kaj storiti.
• Uporabite obvestila, preden uporabnik potrebuje informacije, ne potem.

Ni priporočljivo

• V obvestila ne vključite primerov kode, tabel ali slik.
• Izogibajte se nalaganju obvestil enega na drugega, tudi če so različnih vrst.
• Poskusite ne vstavljati obvestil takoj za naslovi.
• Ne uporabljajte obvestil za določanje predpogojev pred postopkom.

Te najboljše prakse večinoma veljajo za obvestila tipa note , caution in warning , lahko pa veljajo tudi za druge vrste.

Dobri primeri

Naj bo preprosto:

Bodite cautions zaradi morebitne izgube podatkov:

Uporabite warning za morebitne poškodbe:

Uporabite ustrezne vrste obvestil za vsebino, kot je key-term ali success :

Slabi primeri

Obvestila ne smejo biti preveč besedna ali posredovati informacij, ki sodijo v osnovno vsebino:

Obvestila ne smejo določati predpogojev pred postopkom (namesto tega uporabite razdelek »Predpogoji«):