หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- ดิป
- ผู้เขียนด้านเทคนิค:
- อารีชา ทาริค
- ชื่อโปรเจ็กต์:
- การปรับโครงสร้างในระดับสูงและการมุ่งเน้นผู้ใช้ปลายทาง
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (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 Documents, Markdown ฉันชอบไอเดียนี้และอยากต่อยอดเพราะมีประสบการณ์ที่เกี่ยวข้อง และอยากใช้ความรู้และทักษะของตัวเองในการมีส่วนร่วมกับ DIPY ฉันมีประสบการณ์ในด้านการประมวลผลรูปภาพดิจิทัล คอมพิวเตอร์วิทัศน์ และแมชชีนเลิร์นนิง ซึ่งจะช่วยให้ฉันเข้าใจระบบประสาทและช่วยสร้างเอกสารประกอบได้ดีขึ้น ฉันมีประสบการณ์มากมายในด้านการแพทย์ ผมได้พัฒนาเว็บไซต์ทางการแพทย์สำหรับแพทย์ ผู้ป่วย ห้องปฏิบัติการ และคนขับรถพยาบาล ฉันสร้างระบบอื่นที่แพทย์ ผู้ป่วย พยาบาล ผู้ช่วยห้องแล็บ และนักวิจัยใช้กัน ข้อมูลนี้จะช่วยเราในการสร้างเอกสารประกอบที่ผู้ชมจะเข้าใจได้ง่ายขึ้น
เราได้ศึกษาเอกสารของ DIPY และได้จดข้อบกพร่องต่างๆ ไว้ในเอกสารประกอบแล้ว มีช่องโหว่มากมายในเอกสารที่ฉันต้องการปรับปรุง สถานะปัจจุบันของเอกสาร: เอกสารไม่มีโครงสร้างและการออกแบบเฉพาะ อาจเป็นเรื่องน่าเบื่อและเสียเวลาโดยเฉพาะอย่างยิ่งสำหรับผู้ใช้ใหม่ที่จะดูข้อมูลจากคู่มือ ผู้ใช้อาจประสบปัญหาในการรับข้อมูลจากคู่มือ เนื้อหาในเอกสารต้องได้รับการปรับปรุง ในฐานะผู้ใช้ใหม่ ฉันพบว่าการเข้าถึงคู่มือผู้ใช้และคู่มือนักพัฒนาซอฟต์แวร์ทำได้ยาก เอกสารจำเป็นต้องเปลี่ยนโฉมหน้าตาของข้อมูลที่ผู้ใช้ต้องการควรจะเข้าถึงได้ง่าย เอกสารขาดความสอดคล้อง
ฉันวางแผนที่จะดำเนินการต่อไปนี้
กำหนดโครงสร้างและเทมเพลตที่เจาะจงสำหรับเอกสารประกอบ ปรับโครงสร้างเอกสารเพื่อให้ผู้ใช้ไปยังส่วนต่างๆ และค้นหาข้อมูลที่จำเป็นได้อย่างง่ายดาย สร้างแผนกลยุทธ์หรือรายการงานสำหรับการมีส่วนร่วมกับชุมชนในงานเอกสารประกอบเพิ่มเติม กำหนดเทมเพลตสำหรับคู่มือผู้ใช้และคู่มือนักพัฒนาซอฟต์แวร์ กำหนดเทมเพลตสำหรับคู่มือการมีส่วนร่วม เขียนใหม่ ปรับโครงสร้างและอัปเดตคู่มือผู้ใช้ คู่มือการพัฒนาและคู่มือแบบข้อความที่ช่วยเพิ่มประสิทธิภาพให้เอกสารต่างๆ เพื่อช่วยปรับปรุงความสอดคล้องของคำสั่งโครงการ (ช่วยเพิ่มความสอดคล้องกันของคำสั่งโครงการได้)
คู่มือผู้ใช้:
สำหรับคู่มือผู้ใช้ ฉันจะเน้นการใช้ภาษาที่เข้าใจง่ายเพื่อช่วยให้ผู้ใช้เข้าใจระบบที่มีความซับซ้อนมากที่สุด ควรหลีกเลี่ยงการใช้คำศัพท์ ตัวย่อ และข้อมูลภายในอื่นๆ ที่ผู้ใช้ใหม่อาจไม่รู้จักเพื่อประสบการณ์ของผู้ใช้ที่ดียิ่งขึ้น นอกจากนี้ ฉันจะเน้นการใช้เนื้อหาภาพ ซึ่งรวมถึงรูปภาพ ภาพหน้าจอที่มีคำอธิบายประกอบ กราฟิก และวิดีโอ ซึ่งจะแสดงให้ผู้ใช้เห็นวิธีการทำงานของระบบได้อย่างรวดเร็ว เอกสารประกอบที่ดีต้องมีลำดับชั้นของส่วนหัวและส่วนหัวย่อยที่ช่วยให้ผู้ใช้ทราบว่าแต่ละส่วนจะแสดงอะไร และลำดับชั้นดังกล่าวควรเป็นไปตามขั้นตอนเชิงตรรกะที่ช่วยให้ผู้ใช้เรียนรู้วิธีใช้ระบบให้เกิดประโยชน์สูงสุด หนึ่งในวัตถุประสงค์หลักของโครงการนี้คือการสร้างเนื้อหาที่เข้าถึงได้ เอกสารและคำแนะนำทั้งหมดจะมีรูปแบบที่สอดคล้องกัน การใช้แบบอักษรที่สอดคล้องกันและสีที่เสริมกันในเอกสารต่างๆ เป็นสิ่งจำเป็น เราจะตรวจสอบให้แน่ใจว่าผู้ใช้มีสิทธิ์เข้าถึงทรัพยากรขององค์กรเพิ่มเติม ซึ่งจะอธิบายวิธีใช้ระบบให้ประสบความสำเร็จ
คู่มือนักพัฒนาซอฟต์แวร์
คู่มือนักพัฒนาซอฟต์แวร์ประกอบด้วยคำแนะนำและข้อมูลอ้างอิงที่ครอบคลุมเพื่อช่วยนักพัฒนาซอฟต์แวร์ในการสร้างการร่วมให้ข้อมูลสำหรับซอร์สโค้ดของ DIPY แคมเปญนี้พยายามแสดงตัวเลือกต่างๆ ที่มีเพื่อให้คุณใช้แนวทางที่เหมาะสม ทั้งนี้ขึ้นอยู่กับเป้าหมายที่คุณต้องการบรรลุผล คู่มือการพัฒนาซอฟต์แวร์จำเป็นต้องมีการปรับโครงสร้างและปรับโครงสร้าง ฉันจะเขียนเนื้อหาของคู่มือนักพัฒนาซอฟต์แวร์ใหม่ การสร้างทรัพยากร Dependency, คู่มือการมีส่วนร่วม, คู่มือสไตล์, แบบแผนการเขียนโค้ด, คู่มือเอกสารประกอบ, การติดตั้งสภาพแวดล้อมในการพัฒนาซอฟต์แวร์, การแก้ไขข้อบกพร่อง, คู่มือการทดสอบ และข้อมูลที่เกี่ยวข้องจะรวมอยู่ด้วยเพื่อให้นักพัฒนาแอปเข้าถึงได้โดยง่าย เมื่อผู้ร่วมให้ข้อมูลรายใหม่ไฟแรงพุ่งตรงมาที่โครงการของคุณเพื่อร่วมให้ข้อมูลแบบโอเพนซอร์สเป็นครั้งแรก ก็จะต้องพึ่งพาแนวทางในการให้ข้อมูลเพื่อเป็นแนวทาง ดังนั้น หลักเกณฑ์จึงอาจอ่านง่าย ละเอียด และเป็นมิตร คู่มือการร่วมให้ข้อมูลเป็นเอกสารที่มีประโยชน์ซึ่งจะสื่อสารว่าผู้คนจะมีส่วนร่วมกับโครงการโอเพนซอร์สได้อย่างไร การมีส่วนร่วมในโครงการควรทำให้ง่ายและโปร่งใสที่สุดสำหรับผู้ใช้ ไม่ว่าจะเป็นการส่งการแก้ไข การรายงานข้อบกพร่อง การเป็นผู้บำรุงรักษา อภิปรายสถานะปัจจุบันของโค้ด การเสนอฟีเจอร์ใหม่ๆ
TEMPLATE
ซึ่งเป็นหนึ่งในเทมเพลตที่สามารถใช้เป็นคู่มือการสนับสนุนได้ คุณแก้ไขและเพิ่มหรือนำส่วนต่างๆ ออกได้ตามข้อกำหนดของเอกสาร
ร่วมให้ข้อมูลกับ DIPY
- หมายเหตุต้อนรับ
ค่าสารประกอบ
หลักจรรยาบรรณ
- มาตรฐานของเรา
- ตัวอย่างพฤติกรรมที่ก่อให้เกิดการสร้างสภาพแวดล้อมที่ดี
- ตัวอย่างพฤติกรรมที่ยอมรับไม่ได้ของผู้เข้าร่วม
- ความรับผิดชอบของเรา
- ความรับผิดชอบของผู้ดูแลจัดการโครงการ
- ขอบเขต
ขอบเขตของหลักจรรยาบรรณ
ข้อมูลใดบ้างที่ฉันจำเป็นต้องทราบเพื่อให้ความช่วยเหลือ
หากคุณต้องการช่วยเรื่องการเขียนโค้ดที่โปรเจ็กต์ของเราใช้ [ใส่รายการภาษาโปรแกรม เฟรมเวิร์ก หรือเครื่องมือที่โปรเจ็กต์ของคุณใช้] หากยังไม่พร้อมที่จะป้อนรหัส ก็ไม่มีปัญหา นอกจากนี้ คุณยังดูปัญหาเกี่ยวกับเอกสารประกอบ [link to the docs label or tag in your issue tracker] หรือปัญหาการออกแบบที่เรามี [ลิงก์ไปยังการออกแบบป้ายกำกับหรือแท็กในเครื่องมือติดตามปัญหาหากโปรเจ็กต์ติดตามปัญหาการออกแบบ] ได้ด้วย หากคุณสนใจในการร่วมเขียนโค้ดและต้องการเรียนรู้เพิ่มเติมเกี่ยวกับเทคโนโลยีที่เราใช้ โปรดดูรายการด้านล่าง ระบุรายการแหล่งข้อมูลแบบหัวข้อย่อย (วิดีโอ วิดีโอ หนังสือ) ที่ผู้ร่วมให้ข้อมูลรายใหม่สามารถใช้เพื่อเรียนรู้ว่าผู้ใช้จำเป็นต้องทราบอะไรบ้างในการมีส่วนร่วมในโครงการ
การตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์
ในส่วนนี้ เราจะเพิ่มขั้นตอนการติดตั้งและการอ้างอิงที่ต้องติดตั้ง ติดตั้ง $project โดยการเรียกใช้: ติดตั้งโปรเจ็กต์
- ซอร์สโค้ด: github.com/$project/$project
- เครื่องมือติดตามปัญหา: github.com/$project/$project/issues
วิธีการร่วมสนับสนุน
วิธีรายงานข้อบกพร่อง
- ก่อนส่งรายงานข้อบกพร่อง
- ฉันจะส่งรายงานข้อบกพร่อง (ที่ดี) ได้อย่างไร
วิธีส่งการเปลี่ยนแปลง
- โปรโตคอลคำขอพุล
- คำตอบจากทีม
- ความเร็วในการตอบกลับ
วิธีขอการเพิ่มประสิทธิภาพ
- ก่อนส่งคำแนะนำการเพิ่มประสิทธิภาพ
- ฉันจะส่งคำแนะนำการเพิ่มประสิทธิภาพ (ที่ดี) ได้อย่างไร
การมีส่วนร่วมโค้ดครั้งแรก
- ปัญหาระดับเริ่มต้น
- ปัญหาที่ต้องการความช่วยเหลือ #### ดึงคำขอ
- ขั้นตอนการสร้างพุลคำขอ
- ยืนยันว่าการตรวจสอบสถานะทั้งหมดผ่าน
จะเกิดอะไรขึ้นหากการตรวจสอบสถานะล้มเหลว
- แบบทดสอบการเขียน
- การครอบคลุมของการทดสอบ
สไตล์การแปล
- ข้อความคอมมิตของ Git
- รูปแบบมาตรฐาน
การสนับสนุน
โปรดแจ้งให้เราทราบหากพบปัญหา หากต้องการความช่วยเหลือ คุณสอบถามข้อมูลได้จากรายชื่ออีเมลของเราที่ project@google-groups.com, แชท IRC หรือ [ระบุแพลตฟอร์มการสื่อสารอื่นๆ ที่โปรเจ็กต์ของคุณใช้]
ใบอนุญาต
ส่วนนี้จะแสดงเกี่ยวกับใบอนุญาตของโปรเจ็กต์
ข้อผูกพันด้านเวลาและการสื่อสาร:
ฉันจะให้เวลามากกว่า 45 ชั่วโมงต่อสัปดาห์ แต่หากมีเหตุผิดพลาด ฉันจะชดเชยให้ในช่วงสุดสัปดาห์ ในช่วงระยะเวลาสร้างสัมพันธ์ของชุมชน ฉันจะพูดคุยเกี่ยวกับวิธีการสื่อสารและจะสรุปการประชุมรายสัปดาห์ วิธีการ และเวลาสำหรับการประชุมเหล่านั้นกับที่ปรึกษาของฉัน ฉันจะแจ้งให้ Mentor ทราบเกี่ยวกับงานของฉันอยู่เสมอ และจะแชร์รายละเอียดงานของฉันผ่านทางอีเมลกับ Mentor ของฉัน ฉันอยากให้ใช้ TeamViewer มากกว่าในการสื่อสาร เพราะใช้งานง่ายพร้อมฟีเจอร์มากมาย เช่น แชร์หน้าจอ ฯลฯ