Примітки (виноски, примітки, попередження тощо)

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 :

Погані приклади

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

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