ประกาศ (ข้อความเสริม หมายเหตุ คำเตือน ฯลฯ)

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.

Preview

<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 จะขึ้นต้นด้วยคำว่า "หมายเหตุ:" ตัวหนาเสมอ

สำหรับประกาศที่มีมากกว่า 1 ย่อหน้า ให้ใช้ HTML <aside> (และ <p>) แทน

คุณอาจเห็น "สำคัญ:" แทน Note: รูปแบบ Markdown ดังกล่าวจะสร้างการแจ้งเตือนที่มีลักษณะเหมือนกับการแจ้งเตือน Note:

แนวทางปฏิบัติแนะนำ

DevSite ขอแนะนำให้คุณปฏิบัติตามแนวทางปฏิบัติแนะนำต่อไปนี้เมื่อเพิ่มประกาศลงในเอกสารประกอบ

แนะนำ

• กระชับ (พยายามเขียนประกาศให้สั้นๆ เพียง 1-2 ประโยค)
• จำกัดประกาศไว้ที่ 1 รายการต่อหน้า หากเป็นไปได้ (หรือ 1 รายการต่อส่วน หากจำเป็น)
• ตรวจสอบว่าประกาศมีเฉพาะเนื้อหาสำคัญที่ต้องการไฮไลต์เท่านั้น อย่าใส่เนื้อหาในประกาศที่คุณไม่แน่ใจว่าควรทำอย่างไร
• ใช้การแจ้งเตือนก่อนที่ผู้ใช้ต้องการข้อมูล ไม่ใช่หลังจากนั้น

ไม่แนะนำ

• อย่าใส่ตัวอย่างโค้ด ตาราง หรือรูปภาพในหนังสือแจ้ง
• หลีกเลี่ยงการซ้อนประกาศทับซ้อนกัน แม้ว่าจะเป็นประกาศประเภทต่างๆ ก็ตาม
• พยายามอย่าแทรกประกาศไว้หลังส่วนหัว
• อย่าใช้ประกาศเพื่อระบุข้อกําหนดเบื้องต้นก่อนขั้นตอน

แนวทางปฏิบัติแนะนำเหล่านี้ส่วนใหญ่ใช้กับประกาศประเภท note, caution และ warning แต่อาจใช้กับประกาศประเภทอื่นๆ ได้ด้วย

ตัวอย่างที่ดี

ใช้ชื่อที่เรียบง่าย:

ใช้ cautions ในกรณีที่ข้อมูลอาจสูญหาย

ใช้ warning สำหรับอันตรายที่อาจเกิดขึ้น

ใช้การแจ้งเตือนประเภทที่เหมาะสมสำหรับเนื้อหา เช่น key-term หรือ success

ตัวอย่างที่ไม่ดี

ประกาศไม่ควรมีรายละเอียดมากเกินไปหรือสื่อถึงข้อมูลที่ควรอยู่ในเนื้อหาหลัก

ประกาศไม่ควรระบุข้อกําหนดเบื้องต้นก่อนขั้นตอน (ใช้ส่วน "ข้อกําหนดเบื้องต้น" แทน)