บทนำ
Codelab คือบทแนะนำแบบอินเทอร์แอกทีฟที่เขียนด้วยไวยากรณ์ Markdown เราเผยแพร่ Codelab ที่ blocklycodelabs.dev โดยใช้ภาษาธรรมชาติ ตัวอย่างโค้ด และภาพหน้าจอผสมกันเพื่อสร้างประสบการณ์การสอนที่น่าสนใจยิ่งขึ้น ผู้ใช้เป้าหมายของโค้ดแล็บจะทำตาม และเรียกใช้โค้ดขณะอ่าน
การเขียนโค้ดแล็บเป็นวิธีที่ยอดเยี่ยมในการมีส่วนร่วมในชุมชน ซึ่งเป็นวิธี แชร์ความรู้และช่วยให้ชีวิตของนักพัฒนาแอปคนถัดไปที่พบปัญหาเดียวกัน ง่ายขึ้น
Codelab ที่ยอดเยี่ยมมีลักษณะเป็นอย่างไร
Codelab ที่ดีต้องมีเนื้อหาที่ชัดเจนและอ่านง่าย โดยจะบอกให้ผู้ใช้ทราบอย่างชัดเจนว่าผู้ใช้จะสร้างอะไรและจะได้เรียนรู้อะไร รวมถึงจะแนะนำผู้ใช้ในการเขียนและทำความเข้าใจโค้ดเพื่อทำงานที่เฉพาะเจาะจงให้เสร็จสมบูรณ์
กระบวนการ
หากมีไอเดียสำหรับ Codelab คุณสามารถแจ้งให้เราทราบได้โดยการส่งคำขอฟีเจอร์ ในที่เก็บ blockly-samples ระบุคำอธิบายสิ่งที่คุณต้องการ สอนและสิ่งที่คุณจะสร้างในโค้ดแล็บ เราจะพูดคุยและปรับแต่งไอเดีย จากนั้นคุณก็เขียนและส่งคำขอพุลสำหรับ คำขอพุลนั้นได้ เมื่อผ่านการตรวจสอบแล้ว สมาชิกในทีม Blockly จะเผยแพร่บล็อก
เคล็ดลับการเขียน
ส่วนที่เหลือของหน้านี้คือชุดเคล็ดลับและคำถามที่จะช่วยคุณในการ เขียนโค้ดแล็บ
ดูข้อมูลเบื้องต้นเกี่ยวกับการเขียนเชิงเทคนิคได้ที่การเขียนเชิงเทคนิค 1
กลุ่มเป้าหมาย
- ผู้อ่านเป้าหมายคือใคร
- ผู้เรียนรู้อะไรบ้างเกี่ยวกับการใช้ Blockly
- ผู้ใช้พยายามเรียนรู้เรื่องใด
ตั้งค่า
- ผู้ใช้ต้องตั้งค่าขั้นต่ำอะไรบ้างจึงจะเรียกใช้โค้ดของคุณได้
หากต้องการ คุณสามารถเผยแพร่โค้ดเริ่มต้น
และโค้ดที่เสร็จสมบูรณ์
ในไดเรกทอรี examples ได้
โครงสร้าง
เช่นเดียวกับการเขียนอื่นๆ ให้เริ่มด้วยโครงร่าง โครงสร้างที่ดีสำหรับ Codelab ส่วนใหญ่มีดังนี้
- ข้อมูลเบื้องต้น
- สิ่งที่คุณจะได้เรียนรู้
- สิ่งที่คุณจะสร้าง
- สิ่งที่คุณจำเป็นต้องทราบ
- วิธีการตั้งค่า
- ขั้นตอนที่ 1: [Title goes here]
- คำอธิบาย/แรงจูงใจ
- ตัวอย่างโค้ด
- ผลลัพธ์ที่คาดหวัง
- (ไม่บังคับ) คำอธิบายเพิ่มเติม
- ...
- ขั้นตอนที่ 10: [ชื่ออยู่ที่นี่]
- สรุป
- สิ่งที่คุณได้เรียนรู้
- สิ่งที่คุณสร้าง
- แหล่งข้อมูลเพิ่มเติม
- ลิงก์ไปยังโค้ดที่เขียนเสร็จแล้ว (หากมี)
แม้ว่าคุณจะมีขั้นตอนมากกว่า 10 ขั้นตอนได้ แต่หากมีถึง 20 ขั้นตอน คุณควร พิจารณาแบ่งออกเป็น 2 โค้ดแล็บ
รูปแบบการเขียน
- ใช้รูปแบบการเขียนแบบสนทนา
- ใช้ส่วนหัวเพื่อให้การจัดระเบียบชัดเจน
- ใช้รายการหัวข้อย่อยเพื่อแบ่งข้อความยาวๆ
- ใช้รูปภาพและ GIF
รูปแบบโค้ด
- คุณสามารถเขียนใน ES5, ES6 หรือ TypeScript แต่ต้องบอกผู้อ่านว่าคุณใช้ภาษาใดที่ จุดเริ่มต้น
- ปฏิบัติตามคู่มือการเขียนของ Google