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