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