หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- DIPY
- นักเขียนเชิงเทคนิค
- Areesha Tariq
- ชื่อโปรเจ็กต์:
- การปรับโครงสร้างระดับสูงและมุ่งเน้นผู้ใช้ปลายทาง
- ความยาวของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ฉันเป็นวิศวกรซอฟต์แวร์และมีความเชี่ยวชาญในการเขียนเชิงเทคนิค ฉันมีประสบการณ์กว่า 4 ปีในการเขียนเอกสารประกอบซอฟต์แวร์ คู่มือผู้ใช้ คู่มือ คำอธิบายโปรเจ็กต์ที่มีคุณภาพสูง ฉันอาศัยอยู่ในอิสลามาบัด ปากีสถาน (เขตเวลา: UTC + 5) ตอนนี้ฉันทำงานเป็นนักศึกษาฝึกงานใน Outreachy ซึ่งจะสิ้นสุดในวันที่ 18 สิงหาคม ฉันเข้าร่วม Google Season of Docs ในฐานะผู้เขียนเนื้อหาทางเทคนิคในองค์กร OpenELIS Global เอกสารประกอบฉบับเดิมเป็นภาษาฝรั่งเศส มีข้อมูลจำกัด และล้าสมัย เราจึงจัดทำเอกสารประกอบสำหรับผู้ใช้ปลายทางเป็นภาษาอังกฤษที่ครอบคลุมและอัปเดตแล้ว ฉันได้รับเลือกใน Outreachy จากองค์กร Perl & Raku สำหรับรอบเดือนพฤษภาคมถึงสิงหาคม 2020 ในฐานะนักพัฒนาซอฟต์แวร์แบ็กเอนด์ของเซิร์ฟเวอร์ Open Food Facts นอกจากการพัฒนาแบ็กเอนด์แล้ว งานหลักอย่างหนึ่งของการฝึกงานครั้งนี้คือการสร้างเอกสารประกอบสำหรับโมดูลและฟังก์ชันในรูปแบบ POD ฉันได้เข้าสู่โลกของโอเพนซอร์สเมื่อปีที่แล้วเมื่อได้มีส่วนร่วมในโปรเจ็กต์โอเพนซอร์ส 2-3 โปรเจ็กต์ และต่อมาได้เข้าร่วม Google Season of Docs และปีนี้ ฉันได้รับเลือกใน Outreachy ซึ่งสนับสนุนความหลากหลายในซอฟต์แวร์โอเพนซอร์สและซอฟต์แวร์ฟรี ฉันถนัดใช้ Git ค่อนข้างมากเพราะโปรเจ็กต์ Outreachy ของฉันโฮสต์อยู่บน GitHub และได้มีส่วนร่วมกับ Open Food Facts และ Mozilla Fenix เป็นประจำตั้งแต่เดือนมีนาคมเป็นต้นไป ฉันเป็นผู้ใช้ Linux มานานกว่า 3 ปีแล้วและใช้คำสั่งเทอร์มินัลนับตั้งแต่นั้น
เครื่องมือและภาษาที่ใช้เขียนเอกสารประกอบ ได้แก่ Sphinx, Read the docs, Markdown ฉันชอบไอเดียนี้และต้องการนำมาใช้เนื่องจากมีประสบการณ์ที่เกี่ยวข้อง และฉันอยากนำความรู้และทักษะของฉันมาใช้ใน DIPY ฉันมีประสบการณ์ในด้านการประมวลผลภาพดิจิทัล วิสัยทัศน์คอมพิวเตอร์ และแมชชีนเลิร์นนิง ข้อมูลนี้จะช่วยให้เราเข้าใจภาพถ่ายระบบประสาทและช่วยในการสร้างเอกสารประกอบได้ดียิ่งขึ้น ฉันมีประสบการณ์ด้านการแพทย์มาอย่างยาวนาน ฉันพัฒนาเว็บไซต์ทางการแพทย์สำหรับแพทย์ ผู้ป่วย ห้องปฏิบัติการ คนขับรถพยาบาล ฉันทำงานในระบบอื่นที่ใช้โดยแพทย์ ผู้ป่วย พยาบาล ผู้ช่วยห้องทดลอง และนักวิจัย ซึ่งจะช่วยให้เราสร้างเอกสารประกอบที่ผู้ชมเข้าใจได้ง่ายขึ้น
เราได้อ่านเอกสารประกอบของ DIPY และจดข้อบกพร่องหลายประการไว้ในเอกสารประกอบ เอกสารประกอบมีช่องโหว่หลายประการที่เราวางแผนจะปรับปรุง สถานะปัจจุบันของเอกสารประกอบ: เอกสารประกอบไม่มีโครงสร้างและการออกแบบที่เฉพาะเจาะจง การไปยังส่วนต่างๆ อาจเป็นเรื่องน่าเบื่อและเสียเวลา โดยเฉพาะสําหรับผู้ใช้ใหม่ ผู้ใช้อาจพบปัญหาในการรับข้อมูลจากคู่มือ เนื้อหาของเอกสารประกอบต้องได้รับการปรับปรุง ในฐานะผู้ใช้ใหม่ เราพบว่าการเข้าถึงคู่มือผู้ใช้และคู่มือนักพัฒนาแอปเป็นเรื่องยาก เอกสารประกอบต้องปรับรูปแบบใหม่เพื่อให้ผู้ใช้เข้าถึงข้อมูลที่จําเป็นได้โดยง่าย เอกสารประกอบขาดความสอดคล้อง
ฉันวางแผนที่จะดำเนินการต่อไปนี้
กําหนดโครงสร้างและเทมเพลตที่เฉพาะเจาะจงสําหรับเอกสารประกอบ ปรับโครงสร้างเอกสารประกอบเพื่อให้ผู้ใช้ไปยังส่วนต่างๆ และค้นหาข้อมูลที่จําเป็นได้อย่างง่ายดาย สร้างแผนภาพหรือรายการงานเพื่อดึงดูดชุมชนให้มีส่วนร่วมในงานด้านเอกสารประกอบเพิ่มเติม กําหนดเทมเพลตสําหรับคู่มือผู้ใช้และคู่มือนักพัฒนาซอฟต์แวร์ กําหนดเทมเพลตสําหรับคู่มือการมีส่วนร่วม เขียนใหม่ ปรับโครงสร้าง และอัปเดตคู่มือผู้ใช้ คู่มือการพัฒนา และคู่มือการมีส่วนร่วม (ซึ่งช่วยกระตุ้นและจูงใจผู้ใช้ใหม่ให้มีส่วนร่วมในโปรเจ็กต์) เพิ่มรูปภาพที่ไม่มีข้อความเพื่อเสริมคําอธิบายที่เป็นข้อความ ปรับปรุงความสอดคล้องของเอกสารประกอบต่างๆ สร้างเอกสารประกอบสําหรับอินเทอร์เฟซบรรทัดคําสั่งแบบใหม่
คู่มือผู้ใช้
สำหรับคู่มือผู้ใช้ เราขอแนะนำให้ใช้ภาษาที่เข้าใจง่ายและชัดเจนเพื่อช่วยให้ผู้ใช้ได้เข้าใจระบบที่ซับซ้อนที่สุด คุณควรหลีกเลี่ยงศัพท์เฉพาะ ตัวย่อ และข้อมูลวงในอื่นๆ ที่ผู้ใช้ใหม่อาจไม่รู้จัก เพื่อประสบการณ์ของผู้ใช้ที่ดียิ่งขึ้น นอกจากนี้ เราจะมุ่งเน้นการใช้เนื้อหาที่เป็นภาพ ซึ่งรวมถึงรูปภาพ ภาพหน้าจอที่มีคำอธิบายประกอบ กราฟิก และวิดีโอที่แสดงวิธีการทำงานของระบบแก่ผู้ใช้อย่างรวดเร็ว เอกสารประกอบที่ดีต้องมีลําดับชั้นของส่วนหัวและส่วนหัวย่อยที่ช่วยให้ผู้ใช้ทราบว่าแต่ละส่วนจะแสดงอะไร และลําดับชั้นดังกล่าวควรเป็นไปตามขั้นตอนที่สมเหตุสมผลซึ่งช่วยให้ผู้ใช้เรียนรู้วิธีใช้ระบบในวิธีที่เป็นประโยชน์ที่สุด วัตถุประสงค์หลักอย่างหนึ่งของโปรเจ็กต์นี้คือการสร้างเนื้อหาที่เข้าถึงได้ เอกสารและคู่มือทั้งหมดจะใช้รูปแบบที่สอดคล้องกัน การใช้แบบอักษรที่สอดคล้องกันและสีที่ส่งเสริมกันในเอกสารหลายฉบับเป็นสิ่งจําเป็น เราจะตรวจสอบว่าผู้ใช้มีสิทธิ์เข้าถึงทรัพยากรเพิ่มเติมขององค์กรเกี่ยวกับวิธีใช้งานระบบให้ประสบความสำเร็จ
คู่มือนักพัฒนาซอฟต์แวร์:
คู่มือนักพัฒนาซอฟต์แวร์มีคำแนะนำและเอกสารอ้างอิงมากมายที่จะช่วยนักพัฒนาซอฟต์แวร์ในการมีส่วนร่วมในซอร์สโค้ดของ DIPY เครื่องมือนี้จะแสดงตัวเลือกต่างๆ ให้คุณเห็น เพื่อให้คุณใช้แนวทางที่เหมาะสมได้ ทั้งนี้ขึ้นอยู่กับสิ่งที่คุณต้องการบรรลุ คู่มือการพัฒนาต้องปรับรูปแบบและโครงสร้างใหม่ เราจะเขียนเนื้อหาของคู่มือนักพัฒนาซอฟต์แวร์ขึ้นใหม่ จะมีการรวมการสร้างการอ้างอิง คู่มือการมีส่วนร่วม คู่มือสไตล์ รูปแบบการเขียนโค้ด คู่มือเอกสารประกอบ การติดตั้งสภาพแวดล้อมการพัฒนา การแก้ไขข้อบกพร่อง คู่มือการทดสอบ และเนื้อหาที่เกี่ยวข้องไว้เพื่อให้นักพัฒนาซอฟต์แวร์เข้าถึงได้ง่าย เมื่อผู้มีส่วนร่วมใหม่ที่มีความกระตือรือร้นเข้ามาที่โปรเจ็กต์ของคุณเพื่อมีส่วนร่วมในโอเพนซอร์สเป็นครั้งแรก ผู้มีส่วนร่วมเหล่านั้นจะอาศัยหลักเกณฑ์การมีส่วนร่วมเป็นแนวทาง หลักเกณฑ์จึงควรอ่านง่าย ละเอียด และเข้าใจง่าย คู่มือการมีส่วนร่วมเป็นเอกสารที่มีประโยชน์ซึ่งอธิบายวิธีที่ผู้ใช้สามารถมีส่วนร่วมในโปรเจ็กต์โอเพนซอร์ส การมีส่วนร่วมในโปรเจ็กต์ควรทำได้ง่ายและโปร่งใสที่สุดสำหรับผู้ใช้ ไม่ว่าจะเป็นการส่งการแก้ไข การรายงานข้อบกพร่อง การเป็นผู้ดูแล การสนทนาเกี่ยวกับสถานะปัจจุบันของโค้ด หรือการเสนอฟีเจอร์ใหม่
TEMPLATE
นี่เป็นเทมเพลตรายการหนึ่งที่สามารถใช้เป็นคู่มือการมีส่วนร่วมได้ โดยสามารถแก้ไข เพิ่ม หรือนำส่วนต่างๆ ออกได้ตามข้อกำหนดของเอกสาร
การมีส่วนร่วมใน DIPY
- ข้อความต้อนรับ
TOC
หลักจรรยาบรรณ
- มาตรฐานของเรา
- ตัวอย่างพฤติกรรมที่ช่วยให้สภาพแวดล้อมเป็นไปในเชิงบวก
- ตัวอย่างพฤติกรรมที่ผู้เข้าร่วมไม่สามารถยอมรับได้
- ความรับผิดชอบของเรา
- ความรับผิดชอบของผู้ดูแลโปรเจ็กต์
- ขอบเขต
ขอบเขตของหลักจรรยาบรรณ
ฉันจำเป็นต้องทราบข้อมูลอะไรบ้างเพื่อช่วยเหลือคุณ
หากต้องการความช่วยเหลือเกี่ยวกับการสนับสนุนโค้ดที่โปรเจ็กต์ของเราใช้ [ใส่รายการภาษาโปรแกรม เฟรมเวิร์ก หรือเครื่องมือที่โปรเจ็กต์ใช้] หากยังไม่พร้อมที่จะมีส่วนร่วมในการเขียนโค้ด ก็ไม่เป็นไร นอกจากนี้ คุณยังดูปัญหาเกี่ยวกับเอกสารประกอบ [ลิงก์ไปยังป้ายกำกับหรือแท็กเอกสารประกอบในเครื่องมือติดตามปัญหา] หรือปัญหาเกี่ยวกับการออกแบบที่เรามี [ลิงก์ไปยังป้ายกำกับหรือแท็กการออกแบบในเครื่องมือติดตามปัญหา หากโปรเจ็กต์ของคุณติดตามปัญหาการออกแบบ] ได้ด้วย หากสนใจมีส่วนร่วมในการเขียนโค้ดและต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับเทคโนโลยีที่เราใช้ โปรดดูรายการด้านล่าง ใส่รายการทรัพยากร (บทแนะนำ วิดีโอ หนังสือ) แบบหัวข้อย่อยที่ผู้มีส่วนร่วมใหม่สามารถใช้เพื่อดูข้อมูลที่จำเป็นสำหรับผู้ใช้ที่ต้องการมีส่วนร่วมในโครงการ
การตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์
ในส่วนนี้ เราจะเพิ่มขั้นตอนการติดตั้งและทรัพยากร Dependency ที่จำเป็นต้องติดตั้ง ติดตั้ง $project โดยเรียกใช้: install project
- ซอร์สโค้ด: github.com/$project/$project
- เครื่องมือติดตามปัญหา: github.com/$project/$project/issues
วิธีการร่วมสนับสนุน
วิธีรายงานข้อบกพร่อง
- ก่อนส่งรายงานข้อบกพร่อง
- ฉันจะส่งรายงานข้อบกพร่อง (ที่มีประโยชน์) ได้อย่างไร
วิธีส่งการเปลี่ยนแปลง
- โปรโตคอลคำขอพุล
- คำตอบจากทีม
- ความเร็วในการตอบกลับ
วิธีขอการเพิ่มประสิทธิภาพ
- ก่อนส่งคำแนะนำการปรับปรุง
- ฉันจะส่งคำแนะนำในการปรับปรุง (ที่ดี) ได้อย่างไร
การมีส่วนร่วมด้วยโค้ดครั้งแรกของคุณ
- ปัญหาสำหรับผู้เริ่มต้น
- ปัญหาที่ต้องการความช่วยเหลือ #### คำขอพุล
- กระบวนการสร้างคำขอพุล
- ตรวจสอบว่าผ่านการตรวจสอบสถานะทั้งหมด
จะเกิดอะไรขึ้นหากการตรวจสอบสถานะไม่สำเร็จ
- การทดสอบการเขียน
- การครอบคลุมการทดสอบ
คู่มือแนะนำ
- ข้อความคอมมิต Git
- รูปแบบมาตรฐาน
การสนับสนุน
หากพบปัญหา โปรดแจ้งให้เราทราบ หากต้องการความช่วยเหลือ คุณสามารถถามคำถามในรายชื่ออีเมลของเราที่ project@google-groups.com, แชท IRC หรือ [ระบุแพลตฟอร์มการสื่อสารอื่นๆ ที่โปรเจ็กต์ของคุณใช้]
ใบอนุญาต
ส่วนนี้จะบอกเกี่ยวกับใบอนุญาตของโปรเจ็กต์
สัญญาผูกมัดเวลาและการสื่อสาร
ฉันจะให้เวลามากกว่า 45 ชั่วโมงต่อสัปดาห์ แต่ในกรณีที่เกิดอุบัติเหตุ ฉันจะชดเชยเวลานั้นให้ในวันหยุดสุดสัปดาห์ ในช่วงสานสัมพันธ์ของชุมชน ฉันจะพูดคุยถึงวิธีการสื่อสาร และสรุปการประชุมรายสัปดาห์ วิธีการ และเวลาสำหรับการประชุมกับที่ปรึกษาของฉัน ฉันจะแจ้งข้อมูลอัปเดตเกี่ยวกับงานให้ที่ปรึกษาทราบอยู่เสมอ และจะแชร์รายละเอียดงานทางอีเมล เราขอแนะนำให้ใช้ TeamViewer เพื่อสื่อสาร เนื่องจากใช้งานง่ายและมีฟีเจอร์มากมาย เช่น การแชร์หน้าจอ ฯลฯ