הודעות (הסברים, הערות, אזהרות וכו')

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.

ניסוי המוצר לפני הפצה (dogfood)

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

שיטות מומלצות

מומלץ לפעול לפי השיטות המומלצות הבאות כשמוסיפים הודעות למסמכי התיעוד:

מומלץ

• חשוב לנסח את ההודעות בקצרה (כדאי לנסות לכתוב הודעות במשפט אחד או שניים).
• אם אפשר, כדאי להגביל את ההודעות להודעה אחת לכל דף (או להודעה אחת לכל קטע, אם יש צורך).
• חשוב לוודא שההודעות מכילות רק תוכן חשוב שרוצים להדגיש. אל תכללו בהודעות תוכן שאתם לא בטוחים מה לעשות איתו.
• כדאי להשתמש בהתראות לפני שהמשתמש זקוק למידע, ולא אחרי כן.

לא מומלץ

• אסור לכלול בהודעות דוגמאות לקוד, טבלאות או תמונות.
• מומלץ לא להציג הודעות אחת על גבי השנייה, גם אם הן מאותו סוג.
• נסו לא להוסיף הודעות מיד אחרי כותרות.
• אין להשתמש בהודעות כדי לציין תנאים מוקדמים לפני תחילת תהליך.

ברוב המקרים, השיטות המומלצות האלה חלות על הודעות מסוג note,‏ caution ו-warning, אבל הן יכולות לחול גם על הודעות מסוגים אחרים.

דוגמאות טובות

כדאי לשמור על פשטות:

משתמשים ב-cautions במקרה של אובדן נתונים פוטנציאלי:

משתמשים ב-warning כדי לציין פגיעה פוטנציאלית:

משתמשים בסוגי ההודעות המתאימים לתוכן, כמו key-term או success:

דוגמאות גרועות

אסור שההודעות יהיו ארוכות מדי או יכילו מידע ששייך לתוכן הליבה:

אסור לציין בהודעות תנאים מוקדמים לפני פרוצדורה (במקום זאת, צריך להשתמש בקטע 'תנאים מוקדמים'):