Бележки (облачки, бележки, предупреждения и т.н.)

DevSite поддържа няколко стила на известия, представени като полета с различни цветове на фона. Цветовете на фона са предварително дефинирани и можете да създавате известия с помощта на HTML или Markdown.

Налични типове известия

Забележка

HTML 

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

Markdown 

Note: An ordinary note.

Съвет

HTML 

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

Markdown 

Tip: An ordinary tip.

Внимание

HTML 

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

Markdown 

Caution: Suggests proceeding with caution.

Предупреждение

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

важно

HTML 

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

Markdown 

Important: Defines an important concept.

Ключова точка

HTML 

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

Markdown 

Key Point: Defines an important takeaway.

Ключов термин

HTML 

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

Markdown 

Key Term: Defines important terminology.

Обективна

HTML 

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

Markdown 

Objective: Defines the goal of a procedure.

Успех

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.

Бета

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.

Преглед

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.

Вътрешна употреба

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.

Отхвърлено

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.

Бележки за употреба

Използване на HTML

Препоръчваме да използвате тези класове с елемента HTML5 <aside> , но вместо това можете да използвате друг елемент на ниво блок (като <p> ).

HTML класовете определят цвета и иконата на известието, но те не задават автоматично удебелената първа дума; трябва да напишете тази дума ръчно, както е показано в примерите. Теоретично можете да използвате дума, различна от тази, съответстваща на класа, но ви препоръчваме да се придържате към първите думи, показани по-горе.

В по-стари документи може да видите class="special" или нестандартни имена на класове вместо class="note" . Имената на тези класове създават известия, които са визуално идентични с известие note , но препоръчваме да използвате class="note" вместо специални или нестандартни имена на класове.

Използване на маркдаун

Стиловете Markdown определят цвета и иконата на известието и автоматично задават удебелената първа дума на известието. Така например бележка в Markdown винаги започва с думата Note: в удебелен шрифт.

За известие с повече от един абзац използвайте вместо това HTML <aside> (и <p> ).

Може да видите Важно: вместо Note: . Този стил Markdown създава известия, които са визуално идентични с Note: известие.

Най-добри практики

DevSite препоръчва да се придържате към следните най-добри практики, когато добавяте бележки към вашата документация:

Препоръчва се

  • Бъдете кратки (опитайте се да запазите бележките в едно или две изречения).
  • Ограничете известията до едно на страница, ако е възможно (или едно на раздел, ако е необходимо).
  • Уверете се, че известията съдържат само важно съдържание, което искате да маркирате; не включвайте съдържание в известие, с което просто не сте сигурни какво да правите.
  • Използвайте известия преди потребителят да се нуждае от информацията, а не след това.

Не се препоръчва

  • Не включвайте примерни кодове, таблици или изображения в известията.
  • Избягвайте да подреждате известия едно върху друго, дори и да са от различен тип.
  • Опитайте се да не вмъквате бележки непосредствено след заглавията.
  • Не използвайте забележки, за да посочите предварителни условия преди процедура.

В по-голямата си част тези най-добри практики се прилагат за известия от тип note , caution и warning , но могат да се прилагат и за други типове.

Добри примери

Бъдете прости:

cautions за потенциална загуба на данни:

Използвайте warning за потенциално нараняване:

Използвайте подходящи типове известия за съдържание, като key-term или success :

Лоши примери

Известията не трябва да са прекалено многословни или да предават информация, която принадлежи към основното съдържание:

Уведомленията не трябва да посочват предпоставки преди процедура (вместо това използвайте раздел „Предпоставки“):