Megjegyzések (feliratok, megjegyzések, figyelmeztetések stb.)

A DevSite számos értesítési stílust támogat, amelyek különböző háttérszínekkel rendelkező dobozokként jelennek meg. A háttérszínek előre meghatározottak, és HTML vagy Markdown használatával hozhat létre értesítéseket.

Elérhető értesítési típusok

Jegyzet

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

Note: An ordinary note.

Tipp

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

Tip: An ordinary tip.

Vigyázat

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

Caution: Suggests proceeding with caution.

Figyelmeztetés

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

Fontos

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

Important: Defines an important concept.

Kulcsfontosságú pont

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

Key Point: Defines an important takeaway.

Kulcsfogalom

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

Key Term: Defines important terminology.

Célkitűzés

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

Objective: Defines the goal of a procedure.

Siker

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

Előnézet

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

Elavult

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

Használati megjegyzések

HTML használat

Javasoljuk, hogy ezeket az osztályokat használja a HTML5 <aside> elemmel, de használhat egy másik blokkszintű elemet (például <p> ).

A HTML osztályok határozzák meg az értesítés színét és ikonját, de nem állítják be automatikusan a félkövér első szót; ezt a szót kézzel kell beírnia, ahogy a példákban is látható. Elméletileg használhat más szót is, mint az osztálynak megfelelő szó, de javasoljuk, hogy maradjon a fent látható első szavaknál.

A régebbi dokumentumokban class="special" vagy nem szabványos osztályneveket láthat class="note" helyett. Ezek az osztálynevek olyan megjegyzéseket hoznak létre, amelyek vizuálisan megegyeznek a note , de javasoljuk class="note" használatát a speciális vagy nem szabványos osztálynevek helyett.

Leértékelés használat

A Markdown stílusok határozzák meg az értesítés színét és ikonját, és automatikusan beállítják az értesítés első, félkövéren szedett szavát. Így például egy megjegyzés a Markdownban mindig a Megjegyzés: félkövér szóval kezdődik.

Ha egynél több bekezdést tartalmaz, használja a HTML <aside> (és <p> ) kódot.

Note: helyett a Fontos: üzenet jelenhet meg. Ez a Markdown stílus olyan megjegyzéseket hoz létre, amelyek vizuálisan megegyeznek a Note: megjegyzésekkel.

A legjobb gyakorlatok

A DevSite azt javasolja, hogy kövesse az alábbi bevált módszereket, amikor megjegyzéseket ad hozzá a dokumentációhoz:

Ajánlott

• Legyen tömör (próbáljon egy-két mondatos megjegyzéseket tartani).
• Ha lehetséges, korlátozza az értesítéseket oldalanként egyre (vagy szakaszonként egyre, ha szükséges).
• Győződjön meg arról, hogy az értesítések csak olyan fontos tartalmat tartalmaznak, amelyet kiemelni kíván; ne írjon be olyan tartalmat az értesítésbe, amelyről egyszerűen nem tudja, mit kezdjen vele.
• Használja a figyelmeztetéseket, mielőtt a felhasználónak szüksége lenne az információra, ne utána.

Nem ajánlott

• Ne adjon meg kódpéldákat, táblázatokat vagy képeket a közleményekben.
• Kerülje el az értesítések egymásra helyezését, még akkor sem, ha különböző típusúak.
• Próbáljon meg ne közvetlenül a címsorok után megjegyzéseket beszúrni.
• Ne használjon figyelmeztetéseket az eljárás előtti előfeltételek megadására.

Ezek a bevált módszerek többnyire note , caution és warning típusú figyelmeztetésekre vonatkoznak, de vonatkozhatnak más típusokra is.

Jó példák

Legyen egyszerű:

cautions az esetleges adatvesztésre:

Használjon warning az esetleges sérülésekre:

Használjon megfelelő típusú értesítéseket a tartalomhoz, például key-term vagy success :

Rossz példák

A közlemények nem lehetnek túlságosan bőbeszédűek, és nem közölhetnek olyan információkat, amelyek az alapvető tartalomhoz tartoznak:

A közlemények nem határozhatnak meg előfeltételeket az eljárás előtt (használja inkább az „Előfeltételek” részt):