หน้านี้มีรายละเอียดโครงการงานเขียนเชิงเทคนิคที่ได้รับการยอมรับใน Google Season of เอกสาร
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- Creative Commons
- นักเขียนเชิงเทคนิค
- nimishnb
- ชื่อโปรเจ็กต์:
- คู่มือการใช้คําศัพท์
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เรื่องย่อของโปรเจ็กต์
คลังคำศัพท์มีศักยภาพอย่างมากที่จะใช้เป็นไลบรารีคอมโพเนนต์ UI หลักสำหรับการสร้างเว็บไซต์ สิ่งที่ต้องมีคือคำแนะนำวิธีการที่มีประสิทธิภาพและใช้งานง่าย ข้อมูลสำคัญสำหรับนักพัฒนาซอฟต์แวร์ เช่น คู่มือคอมโพเนนต์ ข้อกำหนดเฉพาะในการใช้งาน และการปรับเปลี่ยนการกำหนดค่า เป็นส่วนสำคัญของเอกสารประกอบ การดำเนินการนี้ไม่เพียงแต่จะกระตุ้นให้ผู้ใช้เดิมเห็นภาพว่าคลังคำศัพท์เติบโตอย่างต่อเนื่องและบรรลุเป้าหมายใหม่ได้อย่างไร แต่ยังช่วยส่งเสริมให้ใช้คลังคำศัพท์ในโปรเจ็กต์ที่ใหม่กว่าด้วย ผลลัพธ์ที่ต้องการจากช่วงฝึกงานของฉันไม่เพียงแต่จะเกี่ยวข้องกับการเขียนคู่มือที่เข้าใจง่ายเกี่ยวกับการใช้คอมโพเนนต์ที่มีอยู่ แต่ยังรวมถึงการออกแบบและพัฒนาหน้าแรก (ซึ่งนำไปสู่เอกสารประกอบแบบรวมสำหรับแต่ละรายการ) สำหรับ Vocabulary, Vue-Vocabulary และ Fonts
แผนโปรเจ็กต์
ปัญหา: Documentation เป็นหนึ่งในเหตุผลหลักที่กําหนดความสําเร็จของไลบรารีโอเพนซอร์ส คำถามหลักที่นักพัฒนาซอฟต์แวร์นึกถึงขณะเลือกชุดซอฟต์แวร์โครงสร้างพื้นฐานที่เหมาะสมเพื่อสร้างแอปพลิเคชันคือ "ไลบรารีมีเอกสารประกอบที่ชัดเจนไหม มีการบำรุงรักษาอย่างดีไหม มีการรองรับการใช้งานและข้อผิดพลาดหลายอย่างหรือไม่" คำถามเหล่านี้คือคำถามที่เราควรถามตัวเองเมื่อต้องการหาไอเดียสำหรับโครงการนี้ จากมุมมองวิศวกรซอฟต์แวร์
การวิเคราะห์ข้อกําหนด: เราจําเป็นต้องมีเอกสารประกอบที่กระชับและเป็นเอกภาพเพื่อตอบสนองความต้องการ การไม่มีเอกสารประกอบจะส่งผลเสียต่อมุมมองในอนาคตของแอปพลิเคชันโอเพนซอร์ส และถือเป็นองค์ประกอบที่สำคัญและไม่ควรมองข้าม การลิงก์ไปยังเอกสารประกอบเหล่านี้ควรเป็นหน้าแรกที่ดึงดูดใจ และดึงดูดความสนใจของผู้คนได้ทันที เอกสารควรจัดระเบียบอย่างดีเพื่อให้อ่านได้อย่างราบรื่น
ข้อมูลจำเพาะ: สามารถตัดสินใจได้โดยขึ้นอยู่กับข้อกำหนด เนื้อหาในเอกสารประกอบอาจมาจากข้อมูลที่แสดงในเว็บไซต์ CC netlify ไปพร้อมๆ กับแรงบันดาลใจบางส่วนจากเอกสารที่รู้จักกันดี เช่น semantic-ui, scikit-learn, numpy, Bootstrap ฯลฯ เอาต์พุตของงานนี้จะเป็นหน้า Landing Page ที่จำเป็นและคู่มือเอกสารฉบับเต็ม
ปัญหาทั่วไปบางอย่างที่เกี่ยวข้องกับคําศัพท์, Vue-Vocabulary และแบบอักษรในปัจจุบัน
ไม่มีเอกสารประกอบ และแม้ว่าจะมีเอกสารประกอบอยู่บ้าง แต่เอกสารบางส่วนก็กระจัดกระจายอยู่ในเว็บไซต์ต่างๆ ของ Netlify แต่ไม่ได้ทำให้ผู้ใช้ นักพัฒนาแอป หรือผู้มีส่วนร่วมภายนอกใช้คลังของเราไม่ได้
หากต้องการไปยังคอมโพเนนต์ที่ต้องการและคัดลอกโค้ดที่เกี่ยวข้อง คุณจะต้องคลิกเพิ่มเติม การค้นหาใน Google อย่างง่ายดายสำหรับคำอย่าง "คําศัพท์ CC ของคอมโพเนนต์แท็บ" ไม่ได้แสดงข้อมูลที่คุณต้องการ ตัวเลือกการค้นหาภายในคู่มือเอกสารประกอบจะช่วยปรับปรุง UX ได้มาก
คำอธิบายองค์ประกอบแบบข้อความโดยละเอียดมากขึ้น ซึ่งอธิบายรายละเอียดที่ไม่ชัดเจน
ไม่มีตัวเลือกการเรียกใช้แบบเรียลไทม์ เว็บไซต์ต่างๆ เช่น JSFiddle รองรับการเรียกใช้แบบเรียลไทม์ ซึ่งช่วยให้นักพัฒนาซอฟต์แวร์ได้สัมผัสกับคอมโพเนนต์โดยไม่ต้องเรียกใช้ทั้งแอปพลิเคชันเพื่อดูการทำงาน
โซลูชัน
ปัญหานี้แก้ไขได้หลายวิธี อย่างไรก็ตาม เราจะพูดถึงปัญหาบางส่วนที่นี่และนำเสนอวิธีแก้ปัญหาสุดท้ายในส่วนสรุป
= การใช้ readthedocs readthedocs เป็นโซลูชันที่รู้จักกันดีในการเขียนเอกสารประกอบสำหรับไลบรารีโอเพนซอร์ส โดยอิงตาม Sphinx ซึ่งเป็นเครื่องมือสร้างเอกสารประกอบของ Python
ข้อดี
- รูปแบบการสร้างเอกสารที่ยอมรับอย่างกว้างขวาง ซึ่งองค์กรต่างๆ เช่น Ethereum (Solidity) นำมาใช้
- เอกสารประกอบที่มีโครงสร้างเหมาะสม
- โฮสติ้งแบบคงที่ฟรี
ข้อเสีย
- ควบคุมการจัดรูปแบบไม่ได้เลย
= การใช้ Sphinx เราใช้ Sphinx สำหรับส่วนเอกสารประกอบได้เช่นกัน ซึ่ง Sphinx มีฟีเจอร์ที่มีประโยชน์สำหรับวัตถุประสงค์ทั้งหมดของเรา
ข้อดี
- เครื่องมือ Python ที่ได้รับความนิยมสูงสุดสำหรับเอกสารประกอบ
- รองรับการค้นหาเอกสารประกอบด้วย
- คุณสามารถลบล้าง CSS เริ่มต้นด้วย CSS ที่กําหนดเอง รวมถึงควบคุม HTML บางส่วนได้โดยใช้ไฟล์ .rst
ข้อเสีย
- เกี่ยวข้องกับการเขียนโค้ดใน Python และรูปแบบข้อความที่มีโครงสร้างใหม่ (.rst) ซึ่งจะแตกต่างจากภาษาโปรเจ็กต์ที่แนะนำ
= การใช้ธีม Jekyll ธีม Jekyll ผสานรวมอยู่ในหน้า github และมีเทมเพลตที่มีอยู่ซึ่งปรับแต่งได้ตามความจําเป็น
ข้อดี
- ธีมเอกสารประกอบสำเร็จรูปสำหรับวัตถุประสงค์ทั้งหมด
- CSS และสไตล์เริ่มต้นอาจถูกลบล้างด้วยรายการที่กำหนดเอง รวมถึงควบคุม HTML ด้วย
- ดึง CSS เริ่มต้นของ Primer เพื่อสร้างหน้าเว็บ
- ผสานรวมกับ GitHub Pages ได้อย่างง่ายดาย
ข้อเสีย
- อาจไม่ได้จัดโครงสร้างเอกสารอย่างเหมาะสมที่สุด
=การใช้หน้า GitHub หน้า GitHub มาตรฐานเพื่อสร้างเว็บไซต์แบบคงที่ (HTML, CSS, JS)
ข้อดี
- ควบคุมทุกอย่างที่เป็นปัญหาได้อย่างเต็มที่
- มีความยืดหยุ่นสูงสุดในการกำหนดการออกแบบ สี และสไตล์
- ใช้งานคอมโพเนนต์คําศัพท์ได้ง่าย
- ฝังข้อมูลโค้ดและลิงก์การเรียกใช้แบบเรียลไทม์ได้ง่ายๆ
ข้อเสีย
- อาจใช้เวลานานกว่า
= การใช้ Haroopad วิธีนี้จะแสดงโซลูชัน Markdown ทางเลือกแทน
ข้อดี
- อาจต้องใช้การเขียนโค้ดอย่างซับซ้อนน้อยที่สุด
- เน้นที่การเขียนเอกสารประกอบอย่างสมบูรณ์
ข้อเสีย
- ไม่สามารถควบคุม CSS
- และอาจได้รับการสนับสนุนที่ดีที่สุดจากชุมชน
- อาจไม่รองรับ MDX
= การใช้ MKDocs วิธีนี้จะแสดงโซลูชัน Markdown ทางเลือกอื่นแทน
ข้อดี
- จะต้องมีการใช้โค้ดอย่างซับซ้อน (อีกครั้ง)
- แนวทางเขียนโค้ดน้อยลง
ข้อเสีย
- ไม่สามารถควบคุม CSS
- อาจไม่ได้รับการสนับสนุนจากชุมชนที่ดีที่สุด
- ใช้ Python ซึ่งอาจต้องมีการเปิดใช้งานอินสแตนซ์ Amazon S3 เพิ่มเติม
= การใช้ VueJS +StorybookJS แนวทางนี้มักใช้ในคลังคำศัพท์และที่เก็บข้อมูลที่เกี่ยวข้อง
ข้อดี
- ใช้เทคโนโลยีที่รับประกันว่าใช้งานได้ดีจากประสบการณ์การทำงานที่ผ่านมา
- ความคุ้นเคยกับฐานโค้ด
- ไม่มีเทคโนโลยีที่มีประสิทธิภาพในพื้นที่ทำงานนี้
ข้อเสีย
- อาจมีตัวเลือกที่ใช้ง่ายขึ้นเพื่อวัตถุประสงค์เดียวกันนี้ด้วย
สรุปแล้ว เราคิดว่าแนวทางที่ใช้ VueJS+Storybook (HTML,CSS,JS) น่าจะเหมาะที่สุด เนื่องจากเราคุ้นเคยกับแนวทางนี้ด้วย แต่นั่นก็หมายความว่าเราจะไม่ยอมออกจากการพัฒนาแอปพลิเคชันนี้โดยสมบูรณ์ การใช้องค์ประกอบ CC-Vocabulary ก็ค่อนข้างตรงไปตรงมาเช่นกัน อย่างไรก็ตาม หากต้องการตัดสินใจเกี่ยวกับโครงสร้างของเอกสารประกอบ เราควรพิจารณาวิธีที่เนื้อหาแบ่งออกเป็นส่วนย่อยในหัวเรื่องย่อยในเอกสารประกอบของ readthedocs ฉันประทับใจเว็บไซต์ Semantic-UI (ซึ่งใช้ StoryBook) เพราะมีหน้าตาเรียบง่ายและรู้ว่าต้องการอะไรได้ง่ายๆ ด้วยการคลิกเพียงไม่กี่ครั้ง นอกจาก Semantic-UI แล้ว เรายังดู Material Design, Primer, Bootstrap, Carbon Design และอื่นๆ เพื่อใช้เป็นคู่มือการจัดสไตล์ UI และระบบการออกแบบสำหรับงานของเราด้วย นอกจากนี้ เรายังค้นหาธีมเอกสารประกอบ Jekyll ที่สร้างไว้ล่วงหน้าเพื่อหาแรงบันดาลใจในการสร้างธีมดังกล่าวได้ด้วย