การเขียน Codelab ที่ดี

เกริ่นนำ

Codelab เป็นบทแนะนำแบบอินเทอร์แอกทีฟที่เขียนขึ้นโดยใช้ไวยากรณ์มาร์กดาวน์ เราเผยแพร่ Codelab ที่ blocklycodelabs.dev โดย Codelab จะใช้การผสมผสานระหว่างภาษาธรรมชาติ ตัวอย่างโค้ด และภาพหน้าจอ เพื่อสร้างประสบการณ์บทแนะนำที่น่าสนใจยิ่งขึ้น ผู้ใช้เป้าหมายของ Codelab จะติดตาม และเรียกใช้โค้ดขณะที่อ่าน

การเขียน Codelab เป็นวิธีที่ยอดเยี่ยมในการมีส่วนร่วมกับชุมชน ซึ่งถือเป็นวิธีแชร์ความรู้และทำให้นักพัฒนาซอฟต์แวร์รายต่อไปที่พบปัญหาเดียวกันทำให้ชีวิตง่ายขึ้น

Codelab ที่ดีเป็นอย่างไร

Codelab ที่ดีจะต้องมุ่งเน้นและอ่านต่อ โดยวิธีนี้จะบอกผู้ใช้อย่างชัดเจนเกี่ยวกับ สิ่งที่จะสร้างและเรียนรู้ที่จะเรียนรู้ และแนะนำผู้ใช้ผ่านการเขียนและ ทำความเข้าใจโค้ดเพื่อทำงานหนึ่งๆ ให้เสร็จสมบูรณ์

กระบวนการ

หากมีไอเดียเกี่ยวกับ Codelab ก็แจ้งให้เราทราบได้โดยสร้างคำขอฟีเจอร์ในที่เก็บตัวอย่างแบบบล็อก ใส่คำอธิบายสิ่งที่คุณต้องการสอน และสิ่งที่จะสร้างใน Codelab เราจะมาพูดคุยกัน และปรับแต่งแนวคิดนี้กัน จากนั้นให้เขียนและส่งคำขอพุล เมื่อผ่านการตรวจสอบแล้ว สมาชิกของทีม Blockly จะเผยแพร่เนื้อหาดังกล่าว

เคล็ดลับการเขียน

ส่วนที่เหลือของหน้านี้คือชุดเคล็ดลับและคำถามที่จะแนะนำคุณผ่านการเขียน Codelab

ดูการเขียนเชิงเทคนิคเพื่อดูข้อมูลเบื้องต้นคร่าวๆ เกี่ยวกับการเขียนเชิงเทคนิค

ผู้ชม

  • ใครคือผู้อ่านเป้าหมาย
  • พวกเขารู้อะไรเกี่ยวกับการใช้ Blockly อยู่แล้วบ้าง
  • ผู้ชมพยายามเรียนรู้อะไร

ตั้งค่า

  • ผู้ใช้ต้องมีการตั้งค่าขั้นต่ำเท่าใดในการเรียกใช้โค้ด

คุณจะเผยแพร่โค้ดเริ่มต้นและโค้ดที่สมบูรณ์ในไดเรกทอรี examples ได้หากเป็นประโยชน์

โครงสร้าง

เริ่มต้นด้วยโครงร่าง เช่น การเขียนอื่นๆ นี่เป็นโครงสร้างที่ดีสำหรับ Codelab ส่วนใหญ่

  • บทนำ
    • สิ่งที่คุณจะได้เรียนรู้
    • สิ่งที่คุณจะสร้าง
    • สิ่งที่จำเป็นต้องทราบ
    • วิธีการตั้งค่า
  • ขั้นตอนที่ 1: [ใส่ชื่อที่นี่]
    • คำอธิบาย/แรงจูงใจ
    • ตัวอย่างโค้ด
    • ผลลัพธ์ที่คาดหวัง
    • (ไม่บังคับ) คำอธิบายเพิ่มเติม
  • ...
  • ขั้นตอนที่ 10: [ใส่ชื่อที่นี่]
  • สรุป
    • สิ่งที่คุณได้เรียนรู้
    • สิ่งที่คุณสร้าง
    • แหล่งข้อมูลเพิ่มเติม
    • ลิงก์ไปยังโค้ดที่สมบูรณ์ (หากมี)

แม้ว่าคุณจะมีมากกว่า 10 ขั้นตอน แต่ถ้าไปถึง 20 ขั้นตอนแล้ว คุณควรลองแยก Codelab ออกเป็น 2 ฝั่ง

สไตล์การเขียน

  • ใช้สไตล์การเขียนเชิงสนทนา
  • ใช้ส่วนหัวเพื่อทำให้องค์กรมีความชัดเจน
  • ใช้รายการหัวข้อย่อยเพื่อแบ่งข้อความออกเป็นส่วนย่อย
  • ใช้รูปภาพและ GIF

รูปแบบโค้ด