اعلان ها (پیشنهادات، یادداشت ها، هشدارها و غیره)

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="note" نام‌های کلاس class="special" یا غیراستاندارد را ببینید. نام‌های آن کلاس‌ها اعلامیه‌هایی را تولید می‌کنند که از نظر بصری با اعلان note یکسان هستند، اما توصیه می‌کنیم به جای نام‌های کلاسی خاص یا غیراستاندارد از class="note" استفاده کنید.

استفاده از Markdown

سبک‌های Markdown رنگ و نماد اعلان را تعیین می‌کنند و به‌طور خودکار اولین کلمه پررنگ اعلان را تنظیم می‌کنند. بنابراین، برای مثال، یک یادداشت در Markdown همیشه با کلمه Note: به صورت پررنگ شروع می شود.

برای اطلاعیه ای با بیش از یک پاراگراف، به جای آن از HTML <aside> (و <p> ) استفاده کنید.

ممکن است به جای Note: Important: را ببینید. این سبک Markdown اعلامیه هایی را تولید می کند که از نظر بصری با یک Note: اطلاعیه یکسان هستند.

بهترین شیوه ها

DevSite توصیه می‌کند هنگام افزودن اعلان‌ها به اسناد خود، بهترین روش‌های زیر را رعایت کنید:

توصیه می شود

• مختصر باشید (سعی کنید تذکرات را در یک یا دو جمله نگه دارید).
• در صورت امکان، اعلان‌ها را به یک در هر صفحه (یا در صورت لزوم یکی در هر بخش) محدود کنید.
• اطمینان حاصل کنید که اعلامیه ها فقط حاوی محتوای مهمی هستند که می خواهید برجسته کنید. محتوایی را در اعلامیه ای وارد نکنید که مطمئن نیستید با آن چه کار کنید.
• از اعلامیه ها قبل از نیاز کاربر به اطلاعات استفاده کنید نه بعد از آن.

توصیه نمی شود

• نمونه کد، جداول یا تصاویر را در اعلامیه ها وارد نکنید.
• از چیدن اعلان ها روی هم خودداری کنید، حتی اگر از انواع مختلف باشند.
• سعی کنید بلافاصله بعد از سرفصل ها اعلان ها را وارد نکنید.
• از اعلامیه ها برای تعیین پیش نیازها قبل از یک روش استفاده نکنید.

در بیشتر موارد، این بهترین شیوه‌ها در مورد اعلان‌های نوع note ، caution و warning اعمال می‌شوند، اما می‌توانند برای انواع دیگر اعمال شوند.

نمونه های خوب

آن را ساده نگه دارید:

برای از دست دادن احتمالی داده ها از cautions استفاده کنید:

از warning برای آسیب احتمالی استفاده کنید:

از انواع اعلان مناسب برای محتوا استفاده کنید، مانند key-term یا success :

نمونه های بد

اعلان‌ها نباید بیش از حد پرمخاطب باشند یا اطلاعاتی را که به محتوای اصلی تعلق دارند، منتقل کنند:

اعلان‌ها نباید پیش‌نیازهایی را قبل از یک رویه مشخص کنند (به جای آن از بخش «پیش‌نیازها» استفاده کنید):