หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- มูลนิธิการประมวลผลที่ดำเนินการบนระบบคลาวด์ (CNCF)
- ผู้เขียนด้านเทคนิค:
- ลัทธิ
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบเกี่ยวกับ SMI และโครงข่ายบริการที่เกี่ยวข้อง
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เทคโนโลยีโครงข่ายบริการมีเป้าหมายเพื่อสร้างมูลค่าให้กับบริการที่เพิ่มขึ้นโดยการจัดการความต้องการด้านความปลอดภัย การจัดการ และการตรวจสอบทั้งหมดของคุณ Service Mesh Interface (SMI) กำหนดชุด API สำหรับกรณีการใช้งานโครงข่ายบริการที่พบมากที่สุด (นโยบายการรับส่งข้อมูล การวัดและส่งข้อมูลทางไกล และการย้าย) และเปิดใช้ความเข้ากันได้ระหว่างโครงข่ายบริการ ซึ่งเป็นเลเยอร์โครงสร้างพื้นฐานเฉพาะสำหรับการจัดการการสื่อสารระหว่างบริการถึงบริการในสภาพแวดล้อม Microservice การกำหนดมาตรฐานอินเทอร์เฟซเหล่านี้จะมอบประสบการณ์การใช้งานของผู้ใช้ปลายทางที่มีประสิทธิภาพยิ่งขึ้น ซึ่งเป็นเป้าหมายในอนาคตสำหรับ SMI และโครงข่ายบริการที่เกี่ยวข้อง
สถานะปัจจุบัน:
คู่มือผู้ใช้: SMI เป็นโปรเจ็กต์แซนด์บ็อกซ์ที่ค่อนข้างใหม่ ซึ่งบริจาคให้กับ CNCF ในเดือนเมษายน 2020 ด้วยเหตุนี้ โปรเจ็กต์จึงไม่มีเอกสารสำหรับผู้ใช้ปลายทาง Meshery เป็นระนาบการจัดการบริการที่มีการเปรียบเทียบประสิทธิภาพสำหรับบริการทุกประเภทที่ช่วยอำนวยความสะดวกในการใช้งาน การกำหนดค่า การดำเนินการ และการจัดการประสิทธิภาพของโครงข่ายบริการต่างๆ และรวมการรวบรวมและการแสดงเมตริกจากแอปพลิเคชันที่ทำงานซ้อนกับโครงข่ายบริการทั้งหมด ดังนั้น เราอยากจะเริ่มต้นด้วยคำแนะนำสำหรับ Meshery ซึ่งเป็นจุดเริ่มต้นสำหรับชุมชนผู้ใช้ SMI ทั้งหมด
บทแนะนำสำหรับผู้ใช้: ในบรรดาแพลตฟอร์ม SMI ที่มีอยู่: แอปพลิเคชันตัวอย่าง Learn Layer5 ที่เป็นแอปพลิเคชันการเรียนรู้สำหรับ SMI และเป็นแอปพลิเคชันตัวอย่างสำหรับตรวจสอบข้อกำหนดของ SMI แต่มิเช่นนั้น โครงการ SMI จะไม่มีบทแนะนำผู้ใช้ปลายทางเลย ซึ่งเป็นอุปสรรคสำคัญเนื่องจากลักษณะทางเทคนิคของโปรเจ็กต์สูง Meshery เป็นแอปพลิเคชันที่เหมาะอย่างยิ่งในการแสดงข้อดีและการใช้งานของ SMI รวมถึงโครงข่ายบริการที่เกี่ยวข้อง เราจึงจะใช้ Meshery เป็นเครื่องมือพื้นฐานสำหรับแสดงฟีเจอร์ของ SMI
เอกสารประกอบของ API: ไม่มีอยู่ในขณะนี้ SMI และโปรเจ็กต์ที่เกี่ยวข้องต่างๆ มีการกำหนดปลายทาง API ไว้ในแพลตฟอร์ม ตัวอย่างเช่น Meshery มีปลายทางกำหนดไว้ที่ Server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) แต่ทั้ง 2 อย่างนี้ไม่ได้รับการแสดงความคิดเห็นอย่างดีหรือจัดทำเอกสารไว้ภายนอก ซึ่งปัญหานี้สามารถแก้ไขได้ด้วยเอกสารประกอบที่มีความหมายของ API และสามารถปรับปรุงให้ดีขึ้นได้โดยเพิ่มวิธีให้ผู้ใช้ทดสอบปลายทางและดูตัวอย่างฟีเจอร์
การวิเคราะห์:
บทแนะนำของผู้ใช้นั้นสร้างขึ้นเพื่อให้ผู้ใช้สามารถมีส่วนร่วมและทำการทดสอบซอฟต์แวร์ โฆษณาเหล่านี้ต้องเป็นแบบอินเทอร์แอกทีฟและสวยงามเพื่อคงความสนใจของผู้ใช้ และที่สำคัญที่สุดคือใช้งานง่าย
อย่างไรก็ตาม สำหรับการเขียนหรือโฮสต์ User Guides เราขอแนะนำให้ใช้รูปแบบที่สมบูรณ์มากกว่า เนื่องจากคู่มือผู้ใช้มักจะใช้เป็นคู่มืออ้างอิงหรือที่สำหรับการแก้ไขปัญหาอย่างรวดเร็ว แทนที่จะโต้ตอบ วิดีโอเหล่านี้จะต้องมีโครงสร้างที่ดีและมุ่งเน้นการปรับปรุงความชัดเจน ความสอดคล้องกัน และการไหลเวียนของผู้ใช้ที่ดี
ทางออกที่เป็นไปได้สำหรับเรื่องนี้คือการจัดทำบทแนะนำสำหรับผู้ใช้แยกกันโดยใช้ Google Codelabs และคู่มือผู้ใช้อิสระโดยมี Jekyll เป็นผู้ช่วย และสุดท้ายแล้วก็จะผสานรวมบทแนะนำดังกล่าวเข้ากับเอกสารประกอบของ API เพื่อมอบประสบการณ์การใช้งานที่ครบถ้วนสำหรับทั้งผู้ใช้ปลายทางและผู้ที่ทำงานร่วมกันในอนาคต
ผู้ชมเป้าหมาย: โปรเจ็กต์ SMI มอบแนวทางปฏิบัติด้านการติดตั้งใช้งานและการดำเนินงาน สภาพแวดล้อมการเรียนรู้ และการเปรียบเทียบประสิทธิภาพกับทุกโปรเจ็กต์ที่อยู่ภายใต้โปรเจ็กต์เหล่านั้น บริการนี้เหมาะสำหรับทั้งบุคคลและองค์กร
คู่มือผู้ใช้: ฉันจะกำหนดเป้าหมายผู้ใช้ระดับเริ่มต้น โดยไม่มีข้อสันนิษฐานถึงความรู้ด้านไอทีที่มีอยู่แล้วในฝั่งผู้ใช้ เป้าหมาย: ผู้ใช้ระดับเริ่มต้น เหตุผล: ส่วนใหญ่ใช้เป็นคู่มืออ้างอิงขนาดใหญ่ ซึ่งจะต้องได้รับการอัปเดตเมื่อเวลาผ่านไป ซึ่งจะรวมถึงคำอธิบายเชิงลึกและเคล็ดลับที่มีประโยชน์ เพื่อให้มั่นใจว่าผู้ใช้มีข้อมูลทั้งหมดที่จำเป็นในการตั้งค่าและทำงานกับโครงข่ายบริการ คำแนะนำจะน่าดึงดูดมากขึ้นและใช้ง่ายยิ่งขึ้น โดยการเพิ่มวิดีโอ รูปภาพ ภาพหน้าจอ และ GIF ต่างๆ ได้ตามต้องการ
บทแนะนำสำหรับผู้ใช้: เป้าหมาย: ผู้ใช้มือใหม่ เหตุผล: สิ่งที่มุ่งเน้นคือการทำให้บทแนะนำน่าสนใจและสวยงามเพื่อดึงดูดความสนใจของผู้ใช้ และทำการทดสอบซอฟต์แวร์ได้อย่างราบรื่น ซึ่งจะสร้างความเข้าใจเกี่ยวกับอินเทอร์เฟซ Service Mesh ได้ดียิ่งขึ้น
เอกสารเกี่ยวกับปลายทาง API: เป้าหมาย: ผู้ใช้ขั้นสูง เหตุผล: ส่วนนี้มุ่งเน้นการใช้คุณลักษณะที่ซับซ้อนมากขึ้นของโครงข่ายบริการ ซึ่งมีประโยชน์สำหรับผู้ใช้ที่มีความรู้ด้านไอทีระดับพื้นฐานมากกว่า ผู้ใช้ขั้นสูงจะมองหาบทแนะนำที่กระชับ ซึ่งสามารถใช้เป็นคู่มืออ้างอิงได้หากจำเป็น คุณควรเขียนเอกสารสำหรับปลายทางในลักษณะที่ต้องการเพื่อให้อัปเดตได้ง่ายโดยไม่กระทบต่อความถูกต้องหรือความสอดคล้อง ซึ่งควรเป็นกระบวนการอัตโนมัติ
แหล่งข้อมูล: บทแนะนำของผู้ใช้: Google Developers Codelab - ใช้ในการสร้างบทแนะนำสำหรับผู้ใช้ปลายทางแบบอินเทอร์แอกทีฟที่ครอบคลุม ประโยชน์: - สร้างบทแนะนำเกี่ยวกับแซนด์บ็อกซ์ได้ - มีวิธีการเชิงปฏิบัติ - เขียนโดยใช้ Google เอกสารและสนับสนุนข้อความมาร์กดาวน์ - สามารถตรวจสอบได้โดยใช้ Google Analytics - สังเกตการเข้าชมของผู้ใช้ได้ง่าย - ใช้งานง่าย สร้างบทแนะนำที่สวยงาม ซึ่งช่วยให้ผู้ใช้มีส่วนร่วมกับซอฟต์แวร์ได้โดยตรงโดยไม่ต้องลงทุนโดยตรง
คุณสามารถเพิ่มประสิทธิภาพและทำให้ Google Codelabs ใช้งานได้ง่ายดายโดยใช้โครงการ CLaaT (Codelabs as a Thing) ซึ่งเป็นโปรแกรมที่นำเสนอเครื่องมือบรรทัดคำสั่งที่ใช้แปลงบทแนะนำที่เขียนใน Google เอกสารโดยใช้มาร์กดาวน์ในรูปแบบ Codelab (HTML)
คู่มือผู้ใช้: Jekyll - เอกสารที่มีอยู่สำหรับ meshery.io ซึ่งพบได้ที่นี่โฮสต์ใน Jekyll และใช้ธีม Docsy Jekyll โดยใช้ Markdown, liquid, HTML และ CSS เพื่อสร้างเว็บไซต์ที่พร้อมโฮสต์ คงที่ และทำงานในสภาพแวดล้อมการพัฒนา Ruby ประโยชน์: - โฮสต์เว็บไซต์จากที่เก็บ GitHub ได้โดยตรง - โครงการนี้เป็นโครงการที่ได้รับการสนับสนุนเป็นอย่างดีพร้อมด้วยชุมชนที่กระตือรือร้น - สามารถเพิ่มคู่มือผู้ใช้และการเพิ่มประสิทธิภาพลงในเอกสารเกี่ยวกับ SMI และ Meshery ที่มีอยู่ได้โดยไม่ต้องกังวลเกี่ยวกับการย้ายข้อมูลไปยังแพลตฟอร์มอื่น
เอกสารประกอบเกี่ยวกับ API: Swagger (หรือ Swaggo) จะใช้ในการสร้างเอกสารประกอบเกี่ยวกับ API สำหรับ SMI และ Meshery วิธีนี้เป็นโซลูชันการเขียนเอกสาร API ที่หรูหรา ประโยชน์: - เอกสารประกอบจากการออกแบบ API ของคุณ: ช่วยให้มั่นใจว่าเอกสารของคุณจะมีข้อมูลล่าสุดอยู่เสมอเมื่อ API ของคุณพัฒนา - เอกสารประกอบจากการออกแบบ API ของคุณ: สามารถสร้างโดยอัตโนมัติจากคำจำกัดความของ API - ดูแลรักษาเอกสารหลายเวอร์ชัน - การออกแบบ API ที่กำหนดเอง
เป้าหมายของโครงการ: - ใช้ Codelab สำหรับนักพัฒนาซอฟต์แวร์ของ Google เพื่อสร้างบทแนะนำแบบอินเทอร์แอกทีฟสำหรับ SMI และโครงข่ายบริการที่เกี่ยวข้องโดยใช้ Meshery เป็นเครื่องมือ - สร้างคู่มือผู้ใช้ปลายทางโดยใช้ Jekyll สำหรับโครงข่ายบริการ - ใช้ Swคนหนึ่ง เพื่อสร้างเอกสารประกอบเกี่ยวกับปลายทาง 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
ทำไมต้องมีโครงการนี้ ชุมชนโครงข่ายบริการกำลังขยายตัวอย่างรวดเร็วเนื่องจากการผสานรวมล่าสุดเป็นโปรเจ็กต์แซนด์บ็อกซ์กับ CNCF อย่างไรก็ตาม โครงการนี้ยังมีเอกสารจำนวนมากทั้งสำหรับผู้ใช้ปลายทางและนักพัฒนาซอฟต์แวร์ ผมเคยลองใช้โครงข่ายบริการต่างๆ รวมถึง linkerD กับแอป EmojiVoto, Istio กับแอปพลิเคชัน bookinfo และกงสุลของ Hashicorp และฉันได้ลองใช้การแยกการจราจรของข้อมูล SMI และใช้กฎการตรวจสอบหลายรายการในการกำหนดค่า Mesh แล้ว กระบวนการเรียนรู้นั้นน่าสนใจแต่ก็ต้องอาศัยเทคนิคอย่างมาก จึงอาจช่วยกันชั่วคราวสำหรับผู้ใช้ใหม่รวมถึงนักพัฒนาซอฟต์แวร์ เพื่อที่จะได้เริ่มเข้าสู่ชุมชนโครงข่ายบริการหรือใช้ประโยชน์จากโครงข่ายบริการสำหรับโครงการส่วนบุคคลหรือโครงการมืออาชีพ เราจึงต้องการลดช่องว่างนี้ให้ได้ ซึ่งจะต้องทำได้ก็ต่อเมื่อมีเพียงคำแนะนำและบทแนะนำที่มีประสิทธิภาพและจัดทำเป็นเอกสารไว้เป็นอย่างดีเท่านั้น