หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- Cloud Native Computing Foundation (CNCF)
- นักเขียนเชิงเทคนิค:
- Shriti
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบของ SMI และ Service Mesh ที่เกี่ยวข้อง
- ความยาวของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เทคโนโลยี Service Mesh มีจุดมุ่งหมายหลักในการเพิ่มคุณค่าให้กับบริการที่มีจำนวนเพิ่มขึ้นเรื่อยๆ โดยจัดการกับความต้องการด้านความปลอดภัย การจัดการ และการตรวจสอบทั้งหมด Service Mesh Interface (SMI) จะกำหนดชุด API สำหรับกรณีการใช้งาน Service Mesh ที่พบบ่อยที่สุด (นโยบายการรับส่งข้อมูล การตรวจสอบ และการเปลี่ยน) และช่วยให้ Service Mesh ต่างๆ เข้ากันได้ ซึ่งเป็นเลเยอร์โครงสร้างพื้นฐานเฉพาะสำหรับจัดการการสื่อสารระหว่างบริการในสภาพแวดล้อมแบบ Microservice การกำหนดมาตรฐานอินเทอร์เฟซเหล่านี้จะมอบประสบการณ์การใช้งานที่ดีขึ้นให้แก่ผู้ใช้ปลายทาง และเป็นเป้าหมายในอนาคตสำหรับ SMI และบริการเมชที่เกี่ยวข้อง
สถานะปัจจุบัน:
คู่มือผู้ใช้: SMI เป็นโปรเจ็กต์แซนด์บ็อกซ์ที่ค่อนข้างใหม่ซึ่งบริจาคให้กับ CNCF ในเดือนเมษายน 2020 ด้วยเหตุนี้ โปรเจ็กต์จึงไม่มีเอกสารประกอบสำหรับผู้ใช้ปลายทาง Meshery เป็นแพลตฟอร์มการจัดการบริการที่มีการเปรียบเทียบประสิทธิภาพสำหรับบริการทุกประเภท ซึ่งอำนวยความสะดวกในการนำใช้งาน การกำหนดค่า การดำเนินการ และการจัดการประสิทธิภาพของ Service Mesh ต่างๆ รวมถึงรวมการเก็บรวบรวมและการแสดงเมตริกจากแอปพลิเคชันที่ทำงานอยู่บน Service Mesh ใดก็ได้ เราจึงอยากเริ่มต้นด้วยคู่มือสำหรับ Meshery ซึ่งจะเป็นจุดเริ่มต้นสำหรับชุมชนผู้ใช้ SMI ทั้งหมด
บทแนะนำของผู้ใช้: ในบรรดาแพลตฟอร์ม SMI ที่มีอยู่แล้ว: แอปพลิเคชันตัวอย่าง Learn Layer5 ทำหน้าที่เป็นอุปกรณ์ในการเรียนรู้สำหรับ SMI และเป็นแอปพลิเคชันตัวอย่างในการตรวจสอบความถูกต้องของข้อกำหนด SMI แต่มิเช่นนั้น โครงการ SMI จะไม่มีบทแนะนำของผู้ใช้ปลายทาง ซึ่งเป็นอุปสรรคหลักเพราะลักษณะของโครงการมีลักษณะทางเทคนิคสูง Meshery เป็นแอปพลิเคชันที่เหมาะอย่างยิ่งในการแสดงประโยชน์และการใช้งาน SMI และ Service Mesh ที่เกี่ยวข้อง เราจึงจะใช้ Meshery เป็นเครื่องมือพื้นฐานในการแสดงฟีเจอร์ของ SMI
เอกสารประกอบ API: ยังไม่มีในขณะนี้ SMI และโปรเจ็กต์ที่เกี่ยวข้องต่างๆ มีการกำหนดปลายทาง API ไว้ในแพลตฟอร์ม เช่น Meshery มีการกำหนดปลายทางไว้ที่ server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) แต่ไม่มีการแสดงความคิดเห็นหรือเอกสารประกอบภายนอกอย่างเหมาะสม ซึ่งแก้ไขปัญหานี้ได้ด้วยเอกสารประกอบที่มีความหมายของ API และเพิ่มประสิทธิภาพได้โดยการเพิ่มวิธีต่างๆ ให้ผู้ใช้ทดสอบปลายทางและแสดงตัวอย่างฟีเจอร์
การวิเคราะห์
บทแนะนำของผู้ใช้จะสร้างขึ้นเพื่อให้ผู้ใช้ได้มีส่วนร่วมและทำการทดสอบซอฟต์แวร์ เนื้อหาต้องเป็นแบบอินเทอร์แอกทีฟและดึงดูดสายตาเพื่อดึงดูดความสนใจของผู้ใช้ และที่สำคัญที่สุดคือใช้งานง่าย
อย่างไรก็ตาม หากต้องการเขียนหรือโฮสต์คู่มือผู้ใช้ เราขอแนะนำให้ใช้รูปแบบที่สมบูรณ์มากขึ้น เนื่องจากคู่มือผู้ใช้มักใช้เป็นคู่มืออ้างอิงหรือที่สำหรับแก้ปัญหาอย่างรวดเร็ว วิดีโอต้องได้รับการจัดโครงสร้างอย่างดีและมุ่งเน้นที่การปรับปรุงความชัดเจน ความเชื่อมโยง และขั้นตอนที่สะดวกสําหรับผู้ใช้ แทนที่จะเน้นที่การโต้ตอบ
แนวทางแก้ปัญหาที่เป็นไปได้คือสร้างบทแนะนำผู้ใช้แยกต่างหากโดยใช้ Google Codelabs และคู่มือผู้ใช้อิสระด้วยความช่วยเหลือของ Jekyll และสุดท้ายผสานรวมคู่มือเหล่านั้นเข้ากับเอกสารประกอบ API เพื่อให้ทั้งผู้ใช้ปลายทางและผู้ทำงานร่วมกันในอนาคตได้รับประสบการณ์การใช้งานที่ครอบคลุม
กลุ่มเป้าหมาย: โปรเจ็กต์ SMI มีแนวทางปฏิบัติด้านการใช้งานและการดำเนินงาน สภาพแวดล้อมการเรียนรู้ และเกณฑ์ประสิทธิภาพสำหรับโปรเจ็กต์ทั้งหมดที่อยู่ภายใต้โปรเจ็กต์นั้น โดยให้บริการทั้งแก่บุคคลธรรมดาและองค์กร
คู่มือผู้ใช้: ฉันจะกำหนดเป้าหมายผู้ใช้ระดับเริ่มต้น โดยไม่มีข้อสันนิษฐานว่ามีความรู้ด้านไอทีที่มีอยู่แล้วจากฝั่งผู้ใช้ กลุ่มเป้าหมาย: ผู้ใช้มือใหม่ เหตุผล: ใช้เป็นหลักเป็นคู่มืออ้างอิงขนาดใหญ่ ซึ่งจะต้องมีการอัปเดตเมื่อเวลาผ่านไป ซึ่งจะมีคำอธิบายเชิงลึกและเคล็ดลับที่เป็นประโยชน์ เพื่อให้ผู้ใช้มีข้อมูลทั้งหมดที่จำเป็นในการตั้งค่าและใช้งาน Service Mesh คู่มือนี้จะน่าสนใจและใช้งานง่ายยิ่งขึ้นด้วยการเพิ่มวิดีโอ รูปภาพ ภาพหน้าจอ และ GIF ตามความจําเป็น
บทแนะนำสำหรับผู้ใช้: เป้าหมาย: ผู้ใช้มือใหม่ เหตุผล: เราจะมุ่งเน้นที่การทําให้บทแนะนําน่าสนใจและดึงดูดใจ เพื่อดึงดูดความสนใจของผู้ใช้และช่วยให้การทดสอบซอฟต์แวร์เป็นไปอย่างราบรื่น ซึ่งจะช่วยให้เข้าใจอินเทอร์เฟซ Service Mesh ได้ดียิ่งขึ้น
เอกสารประกอบเกี่ยวกับปลายทาง API: เป้าหมาย: ผู้ใช้ขั้นสูง เหตุผล: ส่วนนี้มุ่งเน้นที่การใช้ฟีเจอร์ที่ซับซ้อนมากขึ้นของ Service Mesh ซึ่งเหมาะกับผู้ใช้ขั้นสูงที่มีความรู้ด้านไอทีในระดับพื้นฐาน ผู้ใช้ขั้นสูงจะมองหาบทแนะนำที่กระชับซึ่งสามารถใช้เป็นคู่มืออ้างอิงได้ด้วยหากจำเป็น เอกสารประกอบของอุปกรณ์ปลายทางควรเขียนในลักษณะดังกล่าวเพื่อให้อัปเดตได้ง่ายโดยไม่กระทบกับความถูกต้องหรือความสอดคล้อง ซึ่งควรเป็นกระบวนการอัตโนมัติ
แหล่งข้อมูล: บทแนะนำผู้ใช้: Google Developers Codelab - ใช้เพื่อสร้างบทแนะนำแบบโต้ตอบและครอบคลุมสำหรับผู้ใช้ปลายทาง ประโยชน์ - สร้างบทแนะนำสำหรับแซนด์บ็อกซ์ได้ - มีแนวทางการปฏิบัติจริง - เขียนโดยใช้ Google เอกสารและรองรับข้อความมาร์กดาวน์ - ตรวจสอบได้โดยใช้ Google Analytics - สังเกตการเข้าชมของผู้ใช้ได้ง่าย - ใช้งานง่าย สร้างบทแนะนำที่ดูดีซึ่งช่วยให้ผู้ใช้มีส่วนร่วมกับซอฟต์แวร์ได้โดยตรงโดยไม่ต้องลงทุนโดยตรง
Google Codelabs สามารถปรับปรุงและทำให้ใช้งานได้อย่างง่ายดายโดยใช้โปรเจ็กต์ CLaaT (Codelabs as a Thing) ซึ่งเป็นโปรแกรมที่มีเครื่องมือบรรทัดคำสั่งที่ใช้แปลงบทแนะนำที่เขียนใน Google เอกสารโดยใช้ Markdown ให้เป็นรูปแบบ Codelabs (HTML)
คู่มือผู้ใช้: Jekyll - เอกสารประกอบที่มีอยู่สำหรับ meshery.io ซึ่งดูได้ที่นี่โฮสต์อยู่บน Jekyll และใช้ธีม Docsy Jekyll โดยใช้ Markdown, Liquid, HTML และ CSS เพื่อสร้างเว็บไซต์ที่พร้อมโฮสต์ แบบคงที่ และเรียกใช้ในสภาพแวดล้อมการพัฒนา Ruby ประโยชน์ - โฮสต์เว็บไซต์จากที่เก็บ GitHub ได้โดยตรง - โครงการนี้เป็นโครงการที่ได้รับการสนับสนุนอย่างดีและมีชุมชนที่แอ็กทีฟมาก - คุณสามารถเพิ่มคู่มือผู้ใช้และการเพิ่มประสิทธิภาพลงในเอกสารประกอบของ SMI และ Meshery ที่มีอยู่ โดยไม่ต้องกังวลเกี่ยวกับการย้ายข้อมูลไปยังแพลตฟอร์มอื่น
เอกสารประกอบของ API: Google จะใช้ของที่ระลึก (หรือที่เรียกว่า Swaggo) ในการสร้างเอกสาร API สำหรับ SMI และ Meshery เครื่องมือนี้เป็นโซลูชันที่ยอดเยี่ยมในการเขียนเอกสาร API ข้อดี ได้แก่ - เอกสารประกอบจากการออกแบบ API: ช่วยให้เอกสารประกอบเป็นปัจจุบันอยู่เสมอเมื่อ API พัฒนาไป - เอกสารประกอบจากการออกแบบ API: สร้างโดยอัตโนมัติจากคําจํากัดความของ API - ดูแลรักษาเอกสารประกอบหลายเวอร์ชัน - การออกแบบ API ที่กําหนดเอง
เป้าหมายของโปรเจ็กต์: - ใช้ Codelab ของนักพัฒนาซอฟต์แวร์ Google เพื่อสร้างบทแนะนำแบบอินเทอร์แอกทีฟสำหรับผู้ใช้ปลายทางเกี่ยวกับ SMI และ Service Mesh ที่เกี่ยวข้องโดยใช้ Meshery เป็นเครื่องมือ - สร้างคู่มือผู้ใช้ปลายทางโดยใช้ Jekyll เป็นโครงข่ายบริการ - ใช้ Swagger เพื่อสร้างเอกสารประกอบเกี่ยวกับปลายทาง API สําหรับ SMI - ทำให้ชุมชนโครงการขับเคลื่อนด้วยเพื่อให้ผู้ใช้หรือนักพัฒนาซอฟต์แวร์ในอนาคตและปัจจุบันสามารถเพิ่มโครงการต่อไปได้โดยง่ายภายใต้คำแนะนำและการดูแลของชุมชน SMI
ไทม์ไลน์: ดูไทม์ไลน์ที่เสนอได้ที่นี่ https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
โครงสร้าง: ดูโครงสร้างที่เสนอสำหรับคู่มือผู้ใช้ได้ที่นี่ https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
เหตุผลที่เลือกโปรเจ็กต์นี้ ชุมชน Service Mesh กำลังเติบโตอย่างรวดเร็ว ด้วยการผสานรวมล่าสุดเป็นโปรเจ็กต์แซนด์บ็อกซ์ใน CNCF อย่างไรก็ตาม โปรเจ็กต์นี้ขาดเอกสารประกอบอย่างร้ายแรง ทั้งสำหรับผู้ใช้ปลายทางและนักพัฒนาแอป เราได้ลองใช้ Service Mesh ต่างๆ มาแล้วในอดีต ซึ่งรวมถึง linkerD กับแอป EmojiVoto, Istio กับแอปพลิเคชัน bookinfo และ Consul ของ Hashicorp เราลองแยกการเข้าชม SMI แล้วและใช้กฎการตรวจสอบต่างๆ ในการกำหนดค่า Service Mesh กระบวนการเรียนรู้นั้นน่าตื่นเต้นแต่มีความเป็นเทคนิคสูง และอาจทำให้ผู้ใช้ใหม่รวมถึงนักพัฒนาแอปที่กำลังจะเริ่มต้นใช้งานชุมชน Service Mesh หรือนำ Service Mesh ไปใช้กับโปรเจ็กต์ส่วนตัวหรือโปรเจ็กต์ระดับมืออาชีพรู้สึกไม่สบายใจ เราต้องการลดช่องว่างนี้ ซึ่งทำได้ด้วยคู่มือและบทแนะนำที่มีประสิทธิภาพและเขียนอย่างละเอียด