หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- มูลนิธิการประมวลผลที่ดำเนินการบนระบบคลาวด์ (CNCF)
- ผู้เขียนด้านเทคนิค:
- Syam Sundar K
- ชื่อโปรเจ็กต์:
- ตัวอย่าง Kubectl ที่ดีและมากขึ้น
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
แรงจูงใจของโครงการนี้คือการปรับปรุงข้อมูลสรุปของ kubectl และเอกสารอ้างอิงที่มีอยู่
เป้าหมายสูงสุดของโปรเจ็กต์นี้คือ • สร้างตัวอย่าง kubectl มากขึ้นและดีขึ้น • เพิ่มตัวอย่าง kubectl ในข้อมูลสรุปของ kubectl • เปลี่ยนโครงสร้างเอกสาร kubectl เพื่อประโยชน์ที่มากที่สุด
เป้าหมาย I - ตัวอย่างสำหรับ kubectl:
เราจะทำงานร่วมกับกลุ่มความสนใจพิเศษ CLI อย่างใกล้ชิดเพื่อดูบริบทของตัวอย่างที่ผู้ใช้ Kubernetes ต้องการมากที่สุดและบันทึกเอาไว้ ซึ่งมีตั้งแต่การปรับปรุงคำสั่ง kubectl ที่มีอยู่ในข้อมูลสรุป ไปจนถึงการเพิ่มคำสั่งใหม่ลงในข้อมูลสรุป
เป้าหมาย II - ประโยชน์ที่เพิ่มมากขึ้นของเอกสาร:
เพื่อให้เอกสารมีประโยชน์มากขึ้น คุณสามารถดำเนินการดังต่อไปนี้
• ขจัดปัญหาสำหรับผู้เริ่มต้น • จัดเรียงคำสั่ง kubectl ใหม่ตามลำดับเพื่อให้มีความต่อเนื่องในลำดับที่เหมาะสม
ขจัดปัญหาสำหรับผู้เริ่มต้นด้วยคำสั่ง / คำอธิบายกรณีของผู้ใช้ที่ดีกว่า อาจดูเหมือนง่าย แต่ก็มีอิทธิพลอย่างมากให้ผู้เริ่มต้นเรียนรู้ต่อหรือเลิกเรียนรู้ได้ ตัวอย่างเช่น เมื่อฉันเริ่มใช้ Kubernetes ผ่าน kubectl ฉันไม่แน่ใจถึงความแตกต่างระหว่างพ็อดและการทำให้ใช้งานได้ ตอนแรกฉันทำให้บริการแบ็กเอนด์ที่เขียนใน Nodejs ใช้งานได้ หลังจากผ่านไป 2-3 ชั่วโมง ฉันอยากจะนำพ็อดออกก็เลยลองลบพ็อด แต่เนื่องจากธรรมชาติของพ็อดถูกสร้างขึ้นอีกครั้งเนื่องจากหายไปเองได้ ฉันงุนงงกับสิ่งที่เกิดขึ้นและสงสัยว่าทำไมมีการสร้างใหม่และไม่ถูกลบ หลังจากค้นหาในเว็บ 2-3 ครั้ง ฉันพบว่าการลบพ็อดไม่เหมือนกับการลบการทำให้ใช้งานได้ สำหรับผู้ที่มีความชำนาญ สิ่งนี้อาจดูเป็นเรื่องง่าย แต่คำอธิบายที่ชัดเจนเพื่อขจัดความไม่ชัดเจนเหล่านี้เป็นสิ่งที่แยกเอกสารที่ดีออกจากเอกสารที่ดี
จัดเรียงคำสั่ง kubectl ใหม่ตามลำดับที่กำหนดเพื่อให้มีความต่อเนื่องในลำดับขั้นตอนที่สมเหตุสมผล ถ้าคุณเป็นผมที่เชื่อมั่นในการเล่าเรื่องราวกับผม ก็คงจะสงสัยว่าจะใส่องค์ประกอบการเล่าเรื่องไว้ในเอกสารที่มีรายการคำสั่งในเทอร์มินัลได้อย่างไร อะไรก็ตามที่เราเรียนรู้จะมีขั้นตอนที่สมเหตุสมผลเสมอ ไม่ว่าจะเป็นจุดเริ่มต้นและจุดสิ้นสุด Kubectl เป็นเครื่องมือบรรทัดคำสั่ง แต่เห็นได้ชัดว่ามีเส้นโค้งการเรียนรู้ ซึ่งที่จริงแล้วเป็นเส้นโค้งการเรียนรู้สอดคล้องกับเส้นโค้งการเรียนรู้ของ Kubernetes เอง เนื่องจากผู้ใช้เกือบทุกคนเริ่มต้นเส้นทางด้วย Kubernetes ผ่าน kubectl (ยกเว้นผู้ที่ใช้ UI ของเว็บ) และเนื่องจากมีเส้นโค้งการเรียนรู้ควบคู่กับเส้นโค้งการเรียนรู้ของ Kubernetes อย่างชัดเจน เอกสารจึงปรับปรุงให้ดีขึ้นได้อย่างมากด้วยการเปลี่ยนลำดับของคำสั่งเหล่านี้และนำเสนอองค์ประกอบการเล่าเรื่อง เช่น อธิบายฟีเจอร์ต่างๆ อย่างการปรับขนาดพ็อดอัตโนมัติแนวนอนหลังจากอธิบายแหล่งข้อมูลพร้อมตัวอย่างและภาพประกอบจากงานจริงแล้ว
เป้าหมาย III - การปรับปรุงความสามารถในการใช้งานเอกสาร:
การย้ายข้อมูลเว็บไซต์ Kubernetes ไปยัง Docsy Hugo ครั้งล่าสุดนั้นยอดเยี่ยมและเป็นการเปลี่ยนแปลงครั้งใหญ่ในมุมมองเอกสาร แม้ว่าการย้ายข้อมูลจะประสบความสำเร็จ แต่ยังมีพื้นที่สำหรับการปรับปรุงอีกหลายอย่างในพื้นที่เอกสาร
ขอแนะนำการเปลี่ยนแปลงบางส่วนดังนี้
• แผงด้านซ้ายจะเลื่อนโดยอัตโนมัติไปที่ส่วนที่ใช้งานอยู่บนเอกสารหลัก - ซึ่งมีประโยชน์ในการติดตามส่วนปัจจุบัน ส่วนที่กำลังจะมาถึง และส่วนที่ผ่านมา • คัดลอกไปยังคลิปบอร์ด - คำสั่งบางคำสั่งอาจยาว ฟังก์ชันคัดลอกอาจเป็นประโยชน์ในการใช้งานคำสั่งประเภทนี้ • การจัดรูปแบบเนื้อหาของไฟล์เอกสาร - หลังการย้ายข้อมูล เนื้อหาในหน้าเว็บบางหน้าไม่ได้มีการจัดรูปแบบอย่างถูกต้อง เช่น ส่วน ประเภททรัพยากร ในภาพรวม kubectl ซึ่งจะทำให้ประสบการณ์ของผู้ใช้แย่ลง
สิ่งเหล่านี้คือการเปลี่ยนแปลงที่จะช่วยปรับปรุงประสบการณ์ของผู้ใช้บนเว็บไซต์ Kubernetes และยังเพิ่มประสิทธิภาพการทำงานของผู้ใช้ได้อีกด้วย