Thông báo (chú thích, ghi chú, cảnh báo, v.v.)

DevSite hỗ trợ một số kiểu thông báo, được trình bày dưới dạng các hộp có màu nền khác nhau. Màu nền được xác định trước và bạn có thể tạo thông báo bằng HTML hoặc Markdown.

Các loại thông báo có sẵn

Lưu ý

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

Note: An ordinary note.

Mẹo

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

Tip: An ordinary tip.

Chú ý

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

Caution: Suggests proceeding with caution.

Nhắc nhở

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

Quan trọng

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

Important: Defines an important concept.

Điểm chính

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

Key Point: Defines an important takeaway.

Từ khoá chính

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

Key Term: Defines important terminology.

Mục tiêu

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

Objective: Defines the goal of a procedure.

Thành công

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

Xem trước

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

Preview: A note or tip for a feature preview.

Thử nghiệm nội bộ

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

Không được dùng nữa

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

Lưu ý về cách sử dụng

Sử dụng HTML

Bạn nên sử dụng các lớp này với phần tử <aside> HTML5, nhưng bạn có thể sử dụng một phần tử cấp khối khác (chẳng hạn như <p>).

Các lớp HTML xác định màu sắc và biểu tượng của thông báo, nhưng không tự động đặt từ đầu tiên được in đậm; bạn cần viết từ đó theo cách thủ công, như trong các ví dụ. Về lý thuyết, bạn có thể sử dụng một từ khác với từ tương ứng với lớp, nhưng bạn nên sử dụng các từ đầu tiên ở trên.

Trong các tài liệu cũ, bạn có thể thấy class="special" hoặc tên lớp không chuẩn thay vì class="note". Những tên lớp đó tạo ra các thông báo giống hệt với thông báo note, nhưng bạn nên sử dụng class="note" thay vì tên lớp đặc biệt hoặc không chuẩn.

Cách sử dụng Markdown

Kiểu Markdown xác định màu sắc và biểu tượng của thông báo, đồng thời tự động đặt từ đầu tiên của thông báo thành in đậm. Ví dụ: một ghi chú trong Markdown luôn bắt đầu bằng từ Note: (Lưu ý:) in đậm.

Đối với thông báo có nhiều đoạn, hãy sử dụng HTML <aside> (và <p>).

Bạn có thể thấy Quan trọng: thay vì Note:. Kiểu Markdown đó tạo ra các thông báo giống hệt với thông báo Note: về mặt hình ảnh.

Các phương pháp hay nhất

DevSite khuyên bạn nên tuân thủ các phương pháp hay nhất sau đây khi thêm thông báo vào tài liệu:

Đề xuất

• Ngắn gọn (cố gắng viết thông báo chỉ trong một hoặc hai câu).
• Giới hạn một thông báo trên mỗi trang nếu có thể (hoặc một thông báo trên mỗi mục nếu cần).
• Đảm bảo rằng thông báo chỉ chứa nội dung quan trọng mà bạn muốn làm nổi bật; đừng đưa nội dung vào thông báo mà bạn không chắc nên làm gì với nội dung đó.
• Hãy sử dụng thông báo trước khi người dùng cần thông tin, chứ không phải sau đó.

Không nên dùng

• Đừng đưa ví dụ về mã, bảng hoặc hình ảnh vào thông báo.
• Tránh xếp chồng các thông báo lên nhau, ngay cả khi chúng thuộc các loại khác nhau.
• Cố gắng không chèn thông báo ngay sau tiêu đề.
• Không sử dụng thông báo để chỉ định các điều kiện tiên quyết trước khi thực hiện một quy trình.

Trong hầu hết trường hợp, các phương pháp hay nhất này áp dụng cho thông báo thuộc loại note, caution và warning, nhưng cũng có thể áp dụng cho các loại khác.

Ví dụ hay

Duy trì sự đơn giản:

Sử dụng cautions khi có khả năng mất dữ liệu:

Sử dụng warning cho các trường hợp có thể gây thương tích:

Sử dụng loại thông báo thích hợp cho nội dung, chẳng hạn như key-term hoặc success:

Ví dụ dở

Thông báo không được quá dài dòng hoặc truyền tải thông tin thuộc nội dung cốt lõi:

Thông báo không được chỉ định các điều kiện tiên quyết trước khi thực hiện một quy trình (hãy sử dụng phần "Điều kiện tiên quyết"):