Pemberitahuan (info, catatan, peringatan, dll.)

DevSite mendukung beberapa gaya pemberitahuan, yang ditampilkan sebagai kotak dengan warna latar belakang yang berbeda. Warna latar belakang telah ditetapkan, dan Anda dapat membuat pemberitahuan menggunakan HTML atau Markdown.

Jenis pemberitahuan yang tersedia

Catatan

HTML

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

Markdown

Note: An ordinary note.

Tips

HTML

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

Markdown

Tip: An ordinary tip.

Perhatian

HTML

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

Markdown

Caution: Suggests proceeding with caution.

Peringatan

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

Penting

HTML

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

Markdown

Important: Defines an important concept.

Poin Utama

HTML

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

Markdown

Key Point: Defines an important takeaway.

Istilah Penting

HTML

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

Markdown

Key Term: Defines important terminology.

Tujuan

HTML

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

Markdown

Objective: Defines the goal of a procedure.

Berhasil

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.

Beta

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.

Pratinjau

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.

Dogfood

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.

Tidak digunakan lagi

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.

Catatan penggunaan

Penggunaan HTML

Sebaiknya gunakan class ini dengan elemen <aside> HTML5, tetapi Anda dapat menggunakan elemen tingkat blok lain (seperti <p>).

Class HTML menentukan warna dan ikon pemberitahuan, tetapi tidak otomatis menetapkan kata pertama yang dicetak tebal; Anda harus menulis kata tersebut secara manual, seperti yang ditunjukkan dalam contoh. Secara teori, Anda dapat menggunakan kata selain yang sesuai dengan class, tetapi sebaiknya Anda tetap menggunakan kata pertama yang ditampilkan di atas.

Dalam dokumen lama, Anda mungkin melihat class="special" atau nama class nonstandar, bukan class="note". Nama class tersebut menghasilkan pemberitahuan yang secara visual identik dengan pemberitahuan note, tetapi sebaiknya gunakan class="note", bukan nama class khusus atau non-standar.

Penggunaan Markdown

Gaya Markdown menentukan warna dan ikon pemberitahuan, serta secara otomatis menetapkan kata pertama yang dicetak tebal dalam pemberitahuan. Jadi, misalnya, catatan dalam Markdown selalu diawali dengan kata Catatan: dalam cetak tebal.

Untuk pemberitahuan dengan lebih dari satu paragraf, gunakan HTML <aside> (dan <p>).

Anda mungkin melihat Penting:, bukan Note:. Gaya Markdown tersebut menghasilkan pemberitahuan yang secara visual identik dengan pemberitahuan Note:.

Praktik terbaik

DevSite merekomendasikan agar Anda mematuhi praktik terbaik berikut saat menambahkan pemberitahuan ke dokumentasi:

Disarankan

  • Buatlah singkat (usahakan agar pemberitahuan hanya terdiri dari satu atau dua kalimat).
  • Batasi pemberitahuan menjadi satu per halaman jika memungkinkan (atau satu per bagian jika diperlukan).
  • Pastikan pemberitahuan hanya berisi konten penting yang ingin Anda soroti; jangan sertakan konten dalam pemberitahuan yang tidak Anda pahami.
  • Gunakan pemberitahuan sebelum pengguna memerlukan informasi, bukan setelahnya.

Tidak Direkomendasikan

  • Jangan sertakan contoh kode, tabel, atau gambar dalam pemberitahuan.
  • Hindari menumpuk pemberitahuan di atas satu sama lain, meskipun jenisnya berbeda.
  • Cobalah untuk tidak menyisipkan pemberitahuan tepat setelah judul.
  • Jangan gunakan pemberitahuan untuk menentukan prasyarat sebelum prosedur.

Sebagian besar, praktik terbaik ini berlaku untuk pemberitahuan jenis note, caution, dan warning, tetapi dapat berlaku untuk jenis lainnya.

Contoh bagus

Simpel:

Gunakan cautions untuk potensi kehilangan data:

Gunakan warning untuk potensi cedera:

Gunakan jenis pemberitahuan yang sesuai untuk konten, seperti key-term atau success:

Contoh buruk

Pemberitahuan tidak boleh terlalu panjang atau menyampaikan informasi yang seharusnya ada dalam konten inti:

pasif

Pemberitahuan tidak boleh menentukan prasyarat sebelum prosedur (gunakan bagian "Prasyarat"):