Уведомления (выноски, примечания, предупреждения и т. д.)

DevSite поддерживает несколько стилей уведомлений, представленных в виде блоков с разными цветами фона. Цвета фона предопределены, и вы можете создавать уведомления с помощью HTML или Markdown.

Доступные типы уведомлений

Примечание

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

Note: An ordinary note.

Кончик

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

Tip: An ordinary tip.

Осторожность

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

Caution: Suggests proceeding with caution.

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

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

Важный

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

Important: Defines an important concept.

Ключевой момент

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

Key Point: Defines an important takeaway.

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

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

Key Term: Defines important terminology.

Цель

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

Objective: Defines the goal of a procedure.

Успех

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

Бета

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

Предварительный просмотр

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

Preview: A note or tip for a feature preview.

Тестовая версия

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

Устарело

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

Примечания по использованию

использование 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 :

Плохие примеры

Уведомления не должны быть слишком многословными или передавать информацию, относящуюся к основному содержанию:

В уведомлениях не следует указывать предварительные условия перед процедурой (вместо этого используйте раздел «Предварительные условия»):