โครงการครีเอทีฟคอมมอนส์

หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs

ข้อมูลสรุปของโปรเจ็กต์

องค์กรโอเพนซอร์ส:

ครีเอทีฟคอมมอนส์

ผู้เขียนด้านเทคนิค:

nimishnb

ชื่อโปรเจ็กต์:

คู่มือการใช้คำศัพท์

ระยะเวลาของโปรเจ็กต์:

ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

ข้อมูลสรุปโครงการ

คำศัพท์มีศักยภาพมากมายที่จะใช้เป็นไลบรารีของคอมโพเนนต์ UI หลักสำหรับการสร้างเว็บไซต์ สิ่งที่แอปนี้ต้องการคือคำแนะนำวิธีใช้ที่มีประสิทธิภาพและเป็นมิตรกับผู้ใช้ทั่วไป ข้อมูลสำคัญของนักพัฒนาซอฟต์แวร์ เช่น คู่มือคอมโพเนนต์ ข้อกำหนดเฉพาะในการใช้งาน และการปรับแต่งการกำหนดค่าเป็นส่วนสำคัญในเอกสารประกอบทั้งหมด ซึ่งไม่เพียงกระตุ้นให้ผู้ใช้ปัจจุบันรู้สึกว่าคำศัพท์พัฒนาขึ้นและบรรลุเป้าหมายใหม่ๆ เท่านั้น แต่ยังส่งเสริมให้มีการใช้คำศัพท์ในโปรเจ็กต์ใหม่ๆ ด้วย ผลที่ได้จากการเป็นนักศึกษาฝึกงานของฉันไม่เพียงเกี่ยวข้องกับการแนะนำการใช้องค์ประกอบที่มีอยู่แล้วเท่านั้น แต่ยังรวมถึงการออกแบบและพัฒนาหน้าแรก (โดยนำไปยังเอกสารประกอบที่รวมไว้ของแต่ละหน้า) สำหรับคำศัพท์, Vue-Vocabulary และ Fonts

แผนโครงการ

1. ปัญหา: เอกสารเป็นหนึ่งในเหตุผลหลักที่กำหนดว่าไลบรารีโอเพนซอร์สหนึ่งๆ จะประสบความสำเร็จมากเพียงใด คำถามสำคัญที่นักพัฒนาซอฟต์แวร์นึกถึงขณะเลือกชุดซอฟต์แวร์โครงสร้างพื้นฐานที่เหมาะสมเพื่อสร้างแอปพลิเคชันคือ "ไลบรารีนี้จัดทำเป็นเอกสารไว้อย่างดีหรือไม่ ได้รับการดูแลอย่างดีหรือไม่ มีการใช้และสนับสนุนข้อผิดพลาดบางอย่างหรือไม่" ซึ่งเป็นคำถามที่เราควรถามตัวเองเมื่อคิดเกี่ยวกับแนวคิดของโครงการนี้ จากมุมมองด้านวิศวกรรมซอฟต์แวร์:

2. การวิเคราะห์ความต้องการ: เราจำเป็นต้องมีเอกสารประกอบที่กระชับและรวมเป็นหนึ่งเดียวสำหรับความต้องการของเรา การขาดเอกสารประกอบจะส่งผลเสียต่อมุมมองในอนาคตของแอปพลิเคชันโอเพนซอร์ส ซึ่งเป็นองค์ประกอบที่สำคัญและไม่มีส่วนสำคัญ การลิงก์ไปยังเอกสารประกอบเหล่านี้ควรเป็นหน้าแรกที่น่าสนใจ ซึ่งจะดึงดูดความสนใจของผู้คนได้ในทันที เอกสารควรเป็นระเบียบเรียบร้อย เพื่อให้ดูได้อย่างราบรื่น

3. ข้อกำหนดเฉพาะ: เลือกข้อมูลจำเพาะได้โดยขึ้นอยู่กับข้อกำหนด เนื้อหาในเอกสารประกอบอาจมาจากข้อมูลที่แสดงในเว็บไซต์ CC แบบ netlify พร้อมด้วยแรงบันดาลใจจากเอกสารประกอบที่รู้จักกันดี เช่น semantic-UI, scikit-learn, numpy, Bootstrap ฯลฯ ผลลัพธ์ของงานนี้จะเป็นหน้า Landing Page ที่จำเป็นและคำแนะนำในเอกสารที่สมบูรณ์

ปัญหาทั่วไปบางประการที่เกี่ยวข้องกับคำศัพท์, Vue-Vocabulary และแบบอักษรในปัจจุบันมีดังนี้

• เนื่องจากไม่มีเอกสารประกอบ และถึงแม้ว่าจะมีเอกสารบางส่วน แต่เอกสารบางส่วนก็กระจัดกระจายอยู่ทั่วทั้งเว็บไซต์ netlify แต่ไม่ได้อนุญาตให้ผู้ใช้ นักพัฒนาซอฟต์แวร์ หรือผู้ร่วมให้ข้อมูลภายนอกใช้ไลบรารีของเรา

  • การคลิกเพิ่มขึ้นจึงจะไปยังคอมโพเนนต์ที่ต้องการและคัดลอกโค้ดที่เกี่ยวข้องได้ การค้นหาง่ายๆ ใน Google ด้วยคำอย่างเช่น "คอมโพเนนต์แท็บ CC คำศัพท์" ไม่แสดงข้อมูลที่ต้องการ ตัวเลือกการค้นหาในคู่มือเอกสารประกอบจะช่วยปรับปรุง UX ได้อย่างมาก

  • คำอธิบายรายละเอียดที่เป็นข้อความเล็กน้อยสำหรับองค์ประกอบต่างๆ โดยอธิบายถึงรายละเอียดที่ไม่ชัดเจน

  • ไม่มีตัวเลือกการทำงานจริง เว็บไซต์ต่างๆ เช่น JSFiddle รองรับการเรียกใช้งานแบบสด ซึ่งช่วยให้นักพัฒนาซอฟต์แวร์เข้าใจคอมโพเนนต์โดยไม่ต้องเรียกใช้ทั้งแอปพลิเคชันเพื่อดูการทำงาน

โซลูชัน

ซึ่งทำได้หลายวิธี อย่างไรก็ตาม ฉันจะอธิบายบางส่วนที่นี่ และนำเสนอวิธีแก้ไขขั้นสุดท้ายในส่วนสรุป:-

= การใช้ readthedocs readthedocs เป็นวิธีแก้ปัญหาที่เป็นที่รู้จักในการเขียนเอกสารสำหรับไลบรารีโอเพนซอร์ส ไฟล์นี้มีพื้นฐานมาจาก Sphinx ซึ่งเป็นเครื่องมือจัดทำเอกสารสำหรับ Python

ข้อดี

1. รูปแบบการจัดทำเอกสารที่ได้รับการยอมรับในวงกว้าง ซึ่งใช้โดยองค์กรต่างๆ เช่น Ethereum (Solidity)
2. เอกสารที่มีการจัดโครงสร้างที่เหมาะสมที่สุด
3. โฮสติ้งแบบคงที่ฟรี

ข้อเสีย

1. ขาดการควบคุมการจัดรูปแบบอย่างสมบูรณ์

= การใช้ Sphinx โดยพื้นฐานแล้วเราอาจใช้สฟิงซ์ในส่วนของเอกสารประกอบด้วย โดยมีฟีเจอร์ที่มีประโยชน์สำหรับวัตถุประสงค์ทั้งหมดของเรา

ข้อดี

1. เครื่องมือ Python ที่ได้รับความนิยมสูงสุดสำหรับการจัดทำเอกสาร
2. มีบริการสนับสนุนการค้นหาเอกสารด้วย
3. คุณสามารถลบล้าง CSS เริ่มต้นด้วย CSS ที่กำหนดเองได้ และมีการควบคุม HTML บางส่วนโดยใช้ไฟล์ .rst

ข้อเสีย

1. จะรวมถึงการเขียนโค้ดใน Python และรูปแบบข้อความที่มีการปรับโครงสร้าง (.rst) ซึ่งจะเบี่ยงเบนไปจากภาษาของโครงการที่แนะนำ

= การใช้ธีม Jekyll ธีม Jekyll มีการรวมไว้ในหน้า GitHub และมีเทมเพลตที่มีอยู่ก่อนแล้วซึ่งสามารถปรับแต่งได้ตามความต้องการของเรา

ข้อดี

1. ธีมเอกสารประกอบสำเร็จรูปที่เหมาะสำหรับทุกวัตถุประสงค์
2. ระบบอาจลบล้าง CSS และรูปแบบเริ่มต้นด้วยรูปแบบที่กำหนดเอง รวมถึงควบคุม HTML ได้ด้วย
3. ดึง Primer CSS เริ่มต้นสำหรับการสร้างหน้าเว็บ
4. ผสานรวมกับหน้า GitHub ได้โดยง่าย

ข้อเสีย

1. อาจไม่ได้ให้เอกสารที่ดีที่สุดเกี่ยวกับการจัดโครงสร้าง

=การใช้หน้า GitHub หน้า GitHub มาตรฐานในการสร้างเว็บไซต์แบบคงที่ (HTML, CSS, JS)

ข้อดี

1. ควบคุมเกือบทุกสิ่งที่เป็นปัญหาได้อย่างเต็มที่
2. ความยืดหยุ่นสูงสุดในการตัดสินใจเลือกเลย์เอาต์ สี และรูปแบบ
3. ใช้งานคอมโพเนนต์คำศัพท์ได้อย่างง่ายดาย
4. ฝังข้อมูลโค้ดและลิงก์การเรียกใช้จริงได้ง่ายๆ

ข้อเสีย

1. อาจเป็นวิธีการที่ใช้เวลานานกว่า

= การใช้ Haroopad วิธีนี้เป็นโซลูชันมาร์กดาวน์ที่เป็นทางเลือก

ข้อดี

1. เกี่ยวข้องกับการเขียนโค้ดอย่างตั้งใจขั้นต่ำ
2. มุ่งเน้นการเขียนเอกสารประกอบอย่างสมบูรณ์

ข้อเสีย

1. ขาดการควบคุม CSS
2. การสนับสนุนจากชุมชนที่ดีที่สุดอาจเพียงพอหรือไม่มีก็ได้
3. อาจไม่รองรับ MDX

= การใช้ MKDocuments ซึ่งเป็นโซลูชันมาร์กดาวน์อื่นแทน

ข้อดี

1. เกี่ยวข้องกับการเขียนโค้ดอย่างตั้งใจขั้นต่ำ (อีกครั้ง)
2. เขียนเพิ่มเติมโดยใช้แนวทาง Code Less

ข้อเสีย

1. ขาดการควบคุม CSS
2. อาจไม่มีการสนับสนุนจากชุมชนที่ดีที่สุด
3. หากใช้ Python คุณอาจต้องสร้างอินสแตนซ์ Amazon S3 ให้มากยิ่งขึ้น

= การใช้ VueJS +StorybookJS แนวทางนี้มักใช้กันทั่วไปในคำศัพท์และที่เก็บข้อมูลร่วม

ข้อดี

1. การยึดถือเทคโนโลยีที่รับประกันว่าจะทำงานได้อย่างราบรื่นจากประสบการณ์การทำงานที่ผ่านมา
2. คุ้นเคยกับฐานของโค้ด
3. ไม่มีเทคโนโลยีที่มีประสิทธิภาพในพื้นที่นี้

ข้อเสีย

1. นอกจากนี้ อาจมีตัวเลือกที่ง่ายกว่าเพื่อวัตถุประสงค์เดียวกันนี้ด้วย

โดยสรุปแล้ว ฉันคิดว่าวิธีการที่เกี่ยวข้องกับ VueJS+Storybook (HTML, CSS,JS) ดูเหมือนจะเหมาะสมที่สุด เพราะใช้แล้วถนัด อย่างไรก็ตาม นี่ยังหมายความว่าเราจะไม่พยายามพัฒนาแอปพลิเคชันนี้ไปโดยสิ้นเชิง การใช้คอมโพเนนต์ CC-Vocabulary ก็ค่อนข้างจะตรงไปตรงมาเหมือนกัน อย่างไรก็ตาม ในการตัดสินใจเกี่ยวกับโครงสร้างของเอกสารนั้น เราควรพิจารณาวิธีแบ่งเนื้อหาตามหัวข้อย่อยในเอกสาร readthedocs ฉันประทับใจเว็บไซต์ Semantic-UI (ซึ่งใช้ StoryBook) เนื่องจากมีรูปลักษณ์ที่เรียบง่ายและเว็บไซต์หนึ่งสามารถทราบถึงสิ่งที่ต้องการได้อย่างง่ายดายหลังจากคลิกไม่กี่ครั้ง นอกจาก UI เชิงความหมายแล้ว เรายังได้ดู Material Design, Primer, Bootstrap, Carbon Design เป็นต้น เพื่อใช้เป็นแนวทางในการจัดรูปแบบ UI และระบบการออกแบบสำหรับงานของฉันด้วย เรายังสามารถหาธีมเอกสารสำเร็จรูปของ Jekyll เพื่อหาแรงบันดาลใจได้ด้วย