หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- gRPC-Gateway
- นักเขียนเชิงเทคนิค:
- iamrajiv
- ชื่อโปรเจ็กต์:
- การปรับโครงสร้างเว็บไซต์เอกสารที่มีอยู่ของ gRPC-Gateway
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ข้อมูลสรุป:
เว็บไซต์เอกสารของผู้ใช้ออกแบบมาเพื่อช่วยเหลือผู้ใช้ปลายทางในการใช้ผลิตภัณฑ์หรือบริการ เว็บไซต์เอกสารประกอบที่ยอดเยี่ยมสําคัญมากเนื่องจากเป็นช่องทางให้ผู้ใช้เรียนรู้วิธีใช้ซอฟต์แวร์ ฟีเจอร์ เคล็ดลับ และวิธีแก้ปัญหาที่พบได้ทั่วไปเมื่อใช้ซอฟต์แวร์ ทั้งยังช่วยลดค่าใช้จ่ายในการสนับสนุนและเป็นส่วนหนึ่งของเอกลักษณ์องค์กรของผลิตภัณฑ์ด้วย เว็บไซต์เอกสารประกอบที่ยอดเยี่ยมสำหรับผู้ใช้เป็นสัญญาณบ่งบอกถึงคุณภาพของผลิตภัณฑ์ ทีมนักพัฒนาซอฟต์แวร์ หากไม่มีเว็บไซต์เอกสารประกอบที่เป็นประโยชน์สําหรับผู้ใช้ ผู้ใช้อาจไม่ทราบวิธีทําสิ่งต่างๆ ข้างต้นอย่างมีประสิทธิภาพ เว็บไซต์เอกสารสำหรับผู้ใช้มีบทบาทสำคัญในการทำให้ผลิตภัณฑ์ประสบความสำเร็จ เนื่องจากการสื่อสารที่ยอดเยี่ยมเป็นหัวใจสำคัญของธุรกิจหรือผลิตภัณฑ์ทุกประเภทและเอกสารประกอบที่ยอดเยี่ยมก็นำการสื่อสารนั้นมาใส่ไว้ในเฟรมเวิร์กที่สามารถจัดการได้ ซึ่งทุกคนสามารถเข้าถึงเพื่อช่วยให้ประสบความสำเร็จ
ขณะเขียนบทความนี้ รีโพซิทอรี่ gRPC-Gateway ได้รับการแยกไปประมาณ 1, 200 ครั้ง และมีผู้คน 184 คนมีส่วนร่วมในรีโพซิทอรี่นี้ ซึ่งแสดงให้เห็นว่าผู้คนจำนวนมากทั่วโลกใช้ gRPC-Gateway และอาจต้องการอ่านเอกสารประกอบสำหรับผู้ใช้เพื่อดูคำแนะนำเกี่ยวกับวิธีใช้ gRPC-Gateway อย่างไรก็ตาม ขณะนี้เอกสารประกอบสำหรับผู้ใช้และเว็บไซต์เอกสารประกอบของ gRPC-Gateway ล้าสมัยและไม่สมบูรณ์ และชุมชน gRPC-Gateway ต้องการใช้โปรเจ็กต์นี้เพื่อรีแฟกทอเรียลเว็บไซต์เอกสารประกอบที่มีอยู่และปรับปรุงเว็บไซต์เอกสารประกอบเพื่อให้ผู้ใช้ปลายทางได้รับประสบการณ์การใช้งานที่ราบรื่นเมื่อใช้ gRPC-Gateway
สถานะปัจจุบัน:
ปัจจุบัน เว็บไซต์เอกสาร gRPC-Gateway มีปัญหาหลัก 2 ประการ ได้แก่
• ปัญหาแรกคือเว็บไซต์เอกสารที่ไม่ดีและล้าสมัย ซึ่งก็คือการจัดสไตล์และโครงสร้างของเว็บไซต์และธีมที่ใช้งานล้าสมัย ไม่สมบูรณ์ ไปยังส่วนต่างๆ หรือค้นหาข้อมูลได้ยาก และไม่ครอบคลุมฟีเจอร์หลายอย่างของเว็บไซต์เอกสารที่ดี การปรับโครงสร้างเว็บไซต์เอกสารที่มีอยู่ของ gRPC-Gateway จะรวมถึงการจัดสไตล์เว็บไซต์ การเพิ่มฟีเจอร์ เช่น การค้นหาเอกสาร ฯลฯ การปรับปรุง UI ของเว็บไซต์ การจัดระเบียบบทแนะนำและตัวอย่างในแถบด้านข้างที่เหมาะสม และการอัปเดตผังงานและรูปภาพที่มีอยู่ด้วยการออกแบบใหม่ ฯลฯ เป้าหมายหลักของเราคือการปรับสไตล์และปรับโครงสร้างเว็บไซต์เอกสารที่มีอยู่
• ปัญหาที่ 2 มีความจำเป็นต้องเปลี่ยนโครงสร้างภายในเอกสาร บทแนะนำ และตัวอย่างต่างๆ ของ gRPC-Gateway ที่มีอยู่ ซึ่งทำได้โดยลบข้อผิดพลาดด้านการพิมพ์และไวยากรณ์ในไฟล์ ปรับแนวข้อมูลโค้ด Go และปรับโครงสร้างตัวอย่างข้อมูล Go ใหม่ตามรูปแบบ Gofmt นอกจากนี้ หากเป็นเช่นนั้น เราอาจเพิ่มเอกสารประกอบ บทแนะนำ และตัวอย่างเพิ่มเติมได้หากจำเป็น หรือจะใช้ไฟล์ที่มีอยู่ซ้ำหลังจากปรับโครงสร้างใหม่ก็ได้ นี่เป็นเป้าหมายรองของฉันและจะทำหลังจากทำเป้าหมายหลักเสร็จแล้ว เช่น การจัดสไตล์และการจัดโครงสร้างเว็บไซต์เอกสารที่มีอยู่
เหตุใดเว็บไซต์เอกสารที่ฉันเสนอจึงดีกว่าเว็บไซต์ปัจจุบัน
เว็บไซต์เอกสารของผู้ใช้ที่เสนอจะมีโครงสร้างเพื่อปรับปรุงและรับประกันประสิทธิภาพ ความสอดคล้อง และความอุ่นใจให้กับผู้ใช้ปลายทาง หน้านี้จะดูดีขึ้นและมี UI ที่ดีขึ้นด้วยส่วนต่างๆ และฟีเจอร์ที่มีสไตล์ดี รวมถึงมีคำแนะนำแบบเขียนและผังงานที่เชื่อมโยงกัน รวมถึงรูปภาพ
เอกสาร gRPC-Gateway ให้คำอธิบายที่ดีของวิธีการและตัวอย่าง แต่ยังคงใช้ธีม Jekyll แบบเก่าอยู่ และปัจจุบันเรามีธีม Jekyll SSG (เครื่องมือสร้างเว็บไซต์แบบคงที่) ที่ดีกว่า นอกจากนี้ เรายังจำเป็นต้องปรับโครงสร้างหน้าเว็บและทำให้หน้าเว็บมีประโยชน์ต่อผู้ใช้มากขึ้นด้วยการเพิ่มตัวอย่างและบทแนะนำใหม่ๆ รวมถึงอัปเดตและเขียนเนื้อหาก่อนหน้านี้ใหม่
โครงสร้างและแผนกลยุทธ์ของเป้าหมายและแนวคิดที่นำเสนอ
เป้าหมายหลักของโปรเจ็กต์นี้:-
เป้าหมายและแนวคิดข้างต้นสามารถนําไปใช้ได้ดังนี้
การเปลี่ยนธีม Jekyll ปัจจุบันเป็นธีมที่ดีขึ้นและมีประสิทธิภาพมากขึ้น เหตุผลที่เราใช้ธีม Jekyll อีกครั้งคือเพื่อให้ผู้ดูแลระบบมีส่วนร่วมและทำความเข้าใจเวิร์กโฟลว์ของโปรเจ็กต์ได้ง่ายขึ้น เนื่องจากผู้ดูแลระบบคุ้นเคยกับเฟรมเวิร์กและธีม Jekyll ที่มีอยู่ซึ่งคล้ายกับธีม Jekyll ใหม่
หลังจากดูธีม Jekyll ต่างๆ ในอินเทอร์เน็ต เราพบว่าธีม https://idratherbewriting.com/documentation-theme-jekyll/ นี้เหมาะกับเว็บไซต์เอกสารประกอบของ gRPC-Gateway มากที่สุดเนื่องจากมีฟีเจอร์ต่อไปนี้
• มาร์กดาวน์:- เพื่อให้นักเขียนด้านเทคนิคไม่ต้องกังวลเกี่ยวกับการติดตั้ง ผู้ใช้สามารถเขียนได้ง่ายๆ ในไฟล์ .md ทุกคนสามารถคลิกปุ่มแก้ไขที่แสดงในเว็บไซต์ (ฟีเจอร์ใหม่) และมีส่วนร่วม (แก้ไข/แนะนำการเปลี่ยนแปลงสำหรับหน้าใน GitHub) เพื่อปรับปรุงให้ดียิ่งขึ้นได้ วิธีนี้จะช่วยดึงดูดผู้ใช้ให้เพิ่มเนื้อหาใหม่หรือแก้ไขเนื้อหาเพื่อปรับปรุง
• การค้นหาเอกสารประกอบ:- ผู้ใช้ควรมีช่องค้นหาเพื่อให้ค้นหาเนื้อหาที่เกี่ยวข้องได้อย่างรวดเร็วและง่ายดาย
• ส่วนความคิดเห็น:- ผู้ใช้อาจมีตัวเลือกให้แสดงความคิดเห็นและแชร์มุมมองเกี่ยวกับโพสต์และบทแนะนำ ผู้ใช้สามารถอ่านมุมมองของผู้อื่นในเอกสารประกอบของโปรเจ็กต์ได้
• บันทึกประจำรุ่นและบล็อกใหม่:- เว็บไซต์ควรมีการอัปเดตบล็อกโพสต์และข่าวใหม่ๆ เกี่ยวกับการพัฒนาและแผนงานปัจจุบัน ดังนั้นควรมีการเขียนบล็อกในหน้า Landing Page
• การพัฒนาที่รวดเร็ว:- เฟรมเวิร์ก SSG (เครื่องมือสร้างเว็บไซต์แบบคงที่) ส่วนใหญ่จะทำงานในเซิร์ฟเวอร์ และการเปลี่ยนแปลงในไฟล์จะแสดงใน UI ทันที นอกจากนี้ กระบวนการทำให้ใช้งานได้และสร้างก็ควรทำได้ง่าย ในอนาคต หากต้องการเปลี่ยนเฟรมเวิร์ก เราจะใช้ จากนั้นทุกอย่างก็ง่ายขึ้น เฟรมเวิร์กส่วนใหญ่รองรับการเขียน Markdown คุณจึงย้ายไฟล์ .md และทําการเปลี่ยนแปลงเล็กน้อยก็เพียงพอแล้ว
ในส่วนนี้เราจะแยกหน้าเว็บไซต์ที่มีอยู่ออกเป็นส่วนต่างๆ และหน้าใหม่ของเว็บไซต์
• หน้า Landing Page:-
หน้า Landing Page ควรระบุฟีเจอร์หลักของ gRPC-Gateway
- การเริ่มต้นใช้งาน gRPC-Gateway (เปลี่ยนเส้นทางไปยังคู่มือผู้ใช้)
- วิธีการติดตั้งแบบง่าย (คำสั่งสั้นๆ)
- เหตุผลที่ควรใช้ gRPC-Gateway
- โปรเจ็กต์ที่ใช้ gRPC-Gateway
ดังนั้นแนวคิดพื้นฐานคือแทนที่จะเขียนรายละเอียดยาวๆ ให้แสดงประเด็นหลักในหน้า Landing Page และระบุลิงก์เพื่อดูรายละเอียด
• หน้าคู่มือผู้ใช้ gRPC-Gateway:-
- คู่มือการติดตั้ง
- เริ่มต้นใช้งานอย่างรวดเร็วด้วย gRPC-Gateway
• หน้าคู่มือนักพัฒนา gRPC-Gateway:-
คู่มือการพัฒนา คู่มือการมีส่วนร่วม การตั้งค่า Git หลักจรรยาบรรณ การตั้งค่าเอกสารประกอบ เวิร์กโฟลว์การพัฒนา ฯลฯ จะชี้ไปยังหน้าเว็บที่คล้ายกันภายใน จึงต้องมีการปรับโครงสร้างและจัดเรียงไฟล์ทั้งหมดใหม่ หน้าการพัฒนาหลักควรมีหน้าเหล่านี้ทั้งหมด และระบบจะสร้างไฮเปอร์ลิงก์ในแต่ละขั้นตอน
• เกี่ยวกับหน้า gRPC-Gateway:-
รายชื่อผู้มีส่วนร่วมทั้งหมดควรแสดงในส่วนทีม จะมีการเพิ่มลิงก์ด่วนและหมายเหตุเกี่ยวกับรุ่น รวมถึงบล็อกล่าสุดเพื่อดึงดูดให้ผู้ใช้อ่านข่าวเกี่ยวกับ gRPC-Gateway ในปัจจุบัน
• หน้าบล็อก บันทึกประจำรุ่น และบทแนะนำ:-
เราคิดว่าเว็บไซต์ควรมีตัวเลือกการเขียนบล็อก เพื่อให้สื่อสารข่าวสารและการเผยแพร่ได้อย่างง่ายดาย หน้าบทแนะนำจะมีบทบรรยายและบทความยอดนิยมที่อธิบาย API และแนวคิดของ gRPC-Gateway ผู้ร่วมให้ข้อมูลจะเพิ่มลิงก์บทแนะนำได้ในหน้าบทแนะนำ
หลังจากทํางานข้างต้นเสร็จแล้ว ให้อัปเดตการเปลี่ยนแปลงเดียวกันในสาขา v2 และทําให้สอดคล้องกับสาขาหลักของ gRPC-Gateway
เป้าหมายรองของโปรเจ็กต์นี้:-
การเปลี่ยนแปลงอื่นๆ ที่จําเป็นต้องทำเพื่อให้เอกสารประกอบ gRPC-Gateway มีประสิทธิภาพและอ่านง่ายขึ้นมีดังนี้
• แก้ไขข้อผิดพลาดทางไวยากรณ์และข้อผิดพลาดในการพิมพ์ รวมถึงจัดระเบียบและจัดแนวลิงก์และโพสต์ในเว็บไซต์ในไฟล์ gRPC-Gateway ที่มีอยู่ทั้งหมด
• เพิ่มเอกสารประกอบและเนื้อหาเพิ่มเติมหากจำเป็นใน gRPC-Gateway เนื่องจากฟีเจอร์ส่วนใหญ่มีเอกสารประกอบสั้นมาก เช่น ในส่วนเอกสารประกอบของเว็บไซต์เกี่ยวกับ AWS, เบื้องหลัง และการใช้งาน เป็นต้น
• การจัดรูปแบบโค้ด Go ของ gRPC-Gateway ให้เป็นไปตามรูปแบบ Gofmt
หลังจากทํางานข้างต้นเสร็จแล้ว ให้อัปเดตการเปลี่ยนแปลงเดียวกันในสาขา v2 และทําให้สอดคล้องกับสาขาหลักของ gRPC-Gateway
เหตุผลที่ฉันเหมาะกับโปรเจ็กต์นี้
เราเชื่อว่าเราเหมาะกับโปรเจ็กต์นี้เนื่องจากเหตุผลต่อไปนี้
• ฉันมีประสบการณ์ที่ผ่านมาในการปรับปรุงเอกสารประกอบขององค์กรและสามารถใช้ระบบควบคุมเวอร์ชันใดก็ได้ ดังนั้นการดำเนินการตามคำสั่งใน GitHub จึงไม่ใช่ปัญหา • นอกจากนี้ สิ่งที่กระตุ้นให้ฉันทำงานคือการทำงานในโปรเจ็กต์ที่สร้างคุณค่าให้กับผู้คน เราเชื่อว่าหากต้องการให้ผู้อื่นทําสิ่งใดสิ่งหนึ่งอย่างมีประสิทธิภาพสูงสุด คุณควรบันทึกไว้ การบันทึกกระบวนการจะช่วยให้ทุกคนที่เกี่ยวข้องทำงานได้อย่างมีประสิทธิภาพ สอดคล้องกัน และวางใจได้ • ฉันคุ้นเคยกับเวิร์กโฟลว์และโค้ดเบสของ gRPC-Gateway เนื่องจากได้มีส่วนร่วมกับ gRPC-Gateway ในช่วง 2 เดือนที่ผ่านมาและได้รับ PR ที่ผสานรวม 11 รายการ