الإشعارات (وسائل الشرح، والملاحظات، والتحذيرات، وما إلى ذلك)

تتيح 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

ننصحك باستخدام هذه الفئات مع عنصر <aside> في HTML5، ولكن يمكنك استخدام عنصر آخر على مستوى الكتلة (مثل <p>) بدلاً من ذلك.

تحدِّد فئات HTML لون الإشعار ورمزه، ولكنها لا تحدِّد تلقائيًا الكلمة الأولى التي تظهر بخط عريض، وعليك كتابة هذه الكلمة يدويًا كما هو موضّح في الأمثلة. من الناحية النظرية، يمكنك استخدام كلمة غير الكلمة المقابلة للفئة، ولكن ننصحك بالالتزام بالكلمات الأولى المعروضة أعلاه.

في المستندات القديمة، قد يظهر لك class="special" أو أسماء فصول غير عادية بدلاً من class="note". تؤدي أسماء الفئات هذه إلى ظهور إشعارات متطابقة من الناحية المرئية مع إشعار note، ولكننا ننصح باستخدام class="note" بدلاً من أسماء الفئات الخاصة أو غير العادية.

استخدام Markdown

تحدِّد أنماط Markdown لون الإشعار ورمزه، كما تحدِّد تلقائيًا الكلمة الأولى في الإشعار التي تظهر بخط عريض. على سبيل المثال، تبدأ ملاحظة في Markdown دائمًا بكلمة Note: (ملاحظة:) بالخط الغامق.

إذا كان الإشعار يتضمّن أكثر من فقرة واحدة، استخدِم علامة HTML <aside> (و<p>) بدلاً من ذلك.

قد يظهر لك "ملاحظة مهمة:" بدلاً من Note:. ينتج أسلوب Markdown هذا إشعارات متطابقة من الناحية المرئية مع إشعار Note:.

أفضل الممارسات

تنصح DevSite بالالتزام بأفضل الممارسات التالية عند إضافة إشعارات إلى مستنداتك:

الخيار الذي ننصح به

• يجب أن تكون الإشعارات موجزة (حاول كتابة إشعارات تتألف من جملة أو جملتين).
• يجب عرض إشعار واحد فقط لكل صفحة إن أمكن (أو إشعار واحد لكل قسم إذا لزم الأمر).
• تأكَّد من أنّ الإشعارات لا تحتوي إلا على المحتوى المهم الذي تريد إبرازه، ولا تُدرِج في الإشعار محتوى لا تعرف كيفية التعامل معه.
• استخدِم الإشعارات قبل أن يحتاج المستخدم إلى المعلومات، وليس بعدها.

لا يُنصح به

• لا تُدرِج أمثلة على الرموز أو الجداول أو الصور في الإشعارات.
• تجنَّب تجميع الإشعارات فوق بعضها، حتى لو كانت من أنواع مختلفة.
• حاول عدم إدراج الإشعارات مباشرةً بعد العناوين.
• لا تستخدِم الإشعارات لتحديد المتطلبات الأساسية قبل إجراء معيّن.

تنطبق أفضل الممارسات هذه في معظم الأحيان على الإشعارات من النوع note وcaution وwarning، ولكن يمكن أن تنطبق على أنواع أخرى.

أمثلة لإعلانات جيدة

البساطة:

استخدِم cautions في حال احتمالية فقدان البيانات:

استخدِم warning للإصابات المحتمَلة:

استخدِم أنواع الإشعارات المناسبة للمحتوى، مثل key-term أو success:

أمثلة لإعلانات سيئة

يجب ألا تكون الإشعارات طويلة جدًا أو تنقل معلومات تندرج ضمن المحتوى الأساسي:

يجب ألا تحدّد الإشعارات المتطلبات الأساسية قبل إجراء معيّن (استخدِم قسم "المتطلبات الأساسية" بدلاً من ذلك):