หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- โคลิบรี
- ผู้เขียนด้านเทคนิค:
- StephDix
- ชื่อโปรเจ็กต์:
- รูปแบบเอกสารประกอบเกี่ยวกับระบบนิเวศของ Kolibri และเวิร์กโฟลว์เวิร์กโฟลว์
- ระยะเวลาของโปรเจ็กต์:
- วิ่งเป็นเวลานาน (5 เดือน)
คำอธิบายโปรเจ็กต์
บทคัดย่อ
เอกสารนี้แสดงรายละเอียดของการนำหลักเกณฑ์ด้านรูปแบบและการจัดการเวิร์กโฟลว์มาใช้กับข้อมูลที่บันทึกไว้ของ Learning Equality สำหรับโปรเจ็กต์ระบบนิเวศ Kolibri
ภาพรวม
ข้อเสนอของฉันประกอบด้วย 4 ระยะ ในช่วงแรก ฉันจะศึกษาแนวทางการช่วยเหลือพิเศษ การเขียน และรูปแบบที่แนะนำของ LE Documentation Style Guide ตามแนวคิดของ LE และหลักเกณฑ์ด้านสไตล์ในการพัฒนาซอฟต์แวร์ ในระยะที่ 2 เราจะดำเนินการตรวจสอบคุณภาพในเอกสารของ ReadTheDocs และ Google เอกสาร แผนการตรวจสอบผสานรวมการใช้เช็กลิสต์เพื่อประเมินความสอดคล้องกับหลักเกณฑ์ด้านสไตล์ รายการตรวจสอบเหล่านี้จะช่วยบันทึกผลการสืบค้นและนำการเปลี่ยนแปลงไปใช้กับเอกสารประกอบ ในระยะที่ 3 ผมจะสร้างโครงสร้าง รูปลักษณ์ และลักษณะของเทมเพลตจาก ReadTheDocs และเอกสาร Google เอกสาร ฉันจะสร้างที่เก็บเทมเพลตและรูปภาพใน Google ไดรฟ์เพื่อระบุหมวดหมู่เทมเพลตของเอกสารหลักในแต่ละหมวดหมู่ เพื่อนำมาใช้ใหม่ในการใช้งานในอนาคต ฉันจะเสริมงานนี้ในการสร้างเทมเพลตเพื่อส่งปัญหาเกี่ยวกับเอกสารเพื่อให้ระบุได้ง่ายในการตรวจสอบพุลคำขอ สุดท้ายนี้ เราจะสร้างคู่มือสำหรับผู้ร่วมให้ข้อมูล ซึ่งจะจัดกลุ่มแหล่งข้อมูลที่มีประโยชน์สำหรับผู้ทำงานร่วมกันแต่ละกลุ่ม เพื่อปรับปรุงประสบการณ์ในการเข้าถึงข้อมูล
วัตถุประสงค์และขอบเขต
แผนการนำไปใช้นี้มีจุดมุ่งหมายเพื่อปรับปรุงประสบการณ์การใช้งานของผู้ใช้เมื่อใช้เอกสารของ Kolibri และช่วยให้สมาชิกในทีมและผู้ร่วมให้ข้อมูลจัดทำเอกสารที่ดียิ่งขึ้นและการทำงานร่วมกันในชุมชน การใช้งานนี้มีผลกับ ReadTheDocs และส่วนย่อยของเอกสาร Google เอกสารในระบบนิเวศ Kolibri
ผู้ชม
กลุ่มเป้าหมายหลักของผู้ติดตั้งใช้งาน ผู้ดูแลระบบ และผู้ใช้ปลายทางซึ่งเป็นผู้บริโภคที่สําคัญที่สุดในเอกสารของ Kolibri กลุ่มเป้าหมายรองของสมาชิกในทีมและผู้ทำงานร่วมกันในการผลิตและการใช้เอกสารประกอบของ Kolibri
วัตถุประสงค์
คู่มือรูปแบบและระบบเวิร์กโฟลว์สำหรับเอกสารประกอบเกี่ยวกับระบบนิเวศของ Kolibri คาดหวังให้ผู้ใช้ จัดทำเอกสารประกอบที่เข้าใจง่ายโดยใช้ภาษาที่เข้าถึงได้และเลย์เอาต์ที่สอดคล้องกัน รักษาแนวทางปฏิบัติด้านคุณภาพไว้เมื่อมีการจัดทำเอกสาร รักษาความสะดวกในการเข้าถึงข้อมูลระหว่างช่องต่างๆ ของเอกสาร ส่งเสริมโครงการริเริ่มด้านการทำงานร่วมกันในชุมชนโอเพนซอร์สของ Kolibri
แหล่งข้อมูล
แหล่งข้อมูลของฉันคือ Kolibri, Kolibri Studio, เอกสาร RTD สำหรับการพัฒนา Kolibri และ Kolibri Toolkit จาก Google ไดรฟ์
คุณ Radina Matic ผู้ยอดเยี่ยมได้ช่วยมอบกิจกรรมอุ่นเครื่องและกิจกรรมต่างๆ สำหรับโครงการโดยเฉพาะ สิ่งที่เธอให้แนวคิดเกี่ยวกับสิ่งที่องค์กรกำหนดเป็น ""หลักเกณฑ์" และ "คู่มือ"" และเรื่องการมีคู่มือสำหรับผู้มีส่วนร่วมช่วยให้ผมจัดระเบียบไอเดียและร่างข้อสรุปได้
ซอฟต์แวร์
ฉันจะพัฒนาฉบับร่างของ Style Guide ใน Google เอกสาร แพลตฟอร์มเอกสารนี้เหมาะอย่างยิ่งสำหรับการทำซ้ำขณะพร้อมสำหรับการเผยแพร่ สำหรับการตรวจสอบ QA ฉันจะใช้ Google ฟอร์มเพื่อดำเนินการและประเมินเอกสาร สเปรดชีตจะเก็บคำตอบของแบบฟอร์มสำหรับการควบคุมเอกสาร ฉันจะเปลี่ยนโครงสร้างเอกสาร RTD โดยใช้ GitHub ผมเคยทำงานกับ Git, Gitkraken, GitHub และ Gitlab ฉันมีความรู้ในการใช้งาน Markdown และ RestructuredText อีกไม่กี่อย่าง ฉันวางแผนที่จะช่วยแก้ไขเอกสารประกอบเพื่อเรียนรู้ไวยากรณ์ต่อ ฉันจะใช้ Sharex สำหรับรูปภาพและ GIF ฉันชอบเครื่องมือนี้เพราะแสดงในรูปแบบเอาต์พุตที่แตกต่างกัน ฉันจะใช้แผนภาพสำหรับการทำแผนภาพและฉบับรูปภาพ ซอฟต์แวร์แผนภาพผสานกับ Google เอกสาร, Google ไดรฟ์ และ LibreOffice ได้อย่างสวยงาม สถานะของเอกสารประกอบ ในขั้นตอนการสำรวจ เราได้แก้ไขเอกสารประกอบส่วนใหญ่ของ Kolibri ฉันพบข้อผิดพลาดทางไวยากรณ์ การพิมพ์ผิด ความไม่สอดคล้องกันของเลย์เอาต์ การพิมพ์ การใช้รูปภาพ รวมถึงเส้นทางเอกสารประกอบที่สับสนจากเอกสารส่วนใหญ่ของโปรเจ็กต์ ตัวอย่างเช่น ในคู่มือผู้ใช้ของ Kolibri ส่วนการแก้ปัญหาจะเป็นหัวข้อย่อย ไม่ใช่หัวข้อ ข้อมูลนี้มีความสำคัญมากเพียงพอสำหรับผู้ใช้ปลายทางที่จะเข้าถึงได้จากสารบัญ อีกทางเลือกที่ 2 คือ นักเรียนสามารถใช้แถบค้นหาและโครงสร้างสารบัญเพื่อขยายหัวข้ออื่นๆ และค้นหาบทความการแก้ปัญหา
หากต้องการเข้าถึงส่วน "การแก้ปัญหา" คุณต้องค้นหาส่วนดังกล่าวหรือขยาย "จัดการ Kolibri" เพื่อให้รู้ว่าการแก้ปัญหามีอยู่ในเอกสารประกอบ คู่มือเทียบกับหลักเกณฑ์ สำหรับข้อเสนอโครงการนี้ ฉันได้วิเคราะห์เอกสาร 2 ฉบับ ได้แก่ คู่มือสไตล์เอกสารสำหรับผู้ใช้ LE Kolibri และแนวทางการแปล LE ในคู่มือ LE Kolibri ฉันให้คำแนะนำและความคิดเห็นจากโครงร่างหัวข้อที่เสนอและแผนเอกสารประกอบ รวมถึงสิ่งอื่นๆ ที่ต้องปรับปรุงในคู่มือ สำหรับหลักเกณฑ์การแปล LE ฉันได้เปลี่ยนรูปแบบและสไตล์ตามคำแนะนำและแบบแผนที่มีอยู่ใน Style Guide สิ่งที่ฉันให้ความสนใจมากที่สุดระหว่างการวิเคราะห์คือความเข้าใจผิดที่เกิดขึ้นระหว่างเอกสารที่จัดอยู่ในหมวดหมู่ "คำแนะนำ" และ "แนวทาง"
ผลลัพธ์
ฉันได้ดำเนินการตรวจสอบคุณภาพใน LE Translation Guide นอกเหนือจากคำแนะนำและความคิดเห็นด้วยแบบฟอร์มเบื้องต้นซึ่งได้อธิบายไว้อย่างละเอียดในงานการตรวจสอบ QA แล้ว ต่อไปนี้เป็นความคิดเห็นสุดท้ายบางส่วนที่ได้จากการประเมิน: ลิงก์เสียสำหรับเว็บไซต์ .js ของไวยากรณ์ ICU รูปแบบที่ใช้สร้างหลักเกณฑ์เหล่านี้ไม่ถูกต้อง เอกสารเป็นคู่มือ ไม่ใช่หลักเกณฑ์ ตัวอักษรไม่สอดคล้องกัน ใช้หัวเรื่องและชื่ออย่างไม่ถูกต้อง การใช้ภาษาที่ไม่เหมาะสม และการใช้การย่อในทางที่ผิด การใช้ข้อความทางเลือกอย่างไม่เหมาะสม ข้อความ/ วิธีการซ้ำๆ
ผลการวิจัยในเอกสารทั้งสองนี้เป็นส่วนหนึ่งของส่วนส่งมอบของข้อเสนอนี้
งานเฉพาะโปรเจ็กต์
- คำแนะนำสไตล์สำหรับคู่มือสไตล์เอกสารสำหรับผู้ใช้ LE (ความคิดเห็น)
- LE Translation Guidelines ที่มีสไตล์และรูปแบบใหม่
- โครงร่างหัวข้อ
- ไทม์ไลน์ของโปรเจ็กต์
- งานด้านเอกสารประกอบ