หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- ScummVM
- ผู้เขียนด้านเทคนิค:
- คาดี
- ชื่อโปรเจ็กต์:
- เปิดตัวพอร์ทัลเอกสาร
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
วัตถุประสงค์:
- เพื่อสร้างเอกสารสำหรับผู้ใช้ปลายทางที่มีเวอร์ชันและมีคุณภาพสูง โดยการรวมข้อมูลปริมาณมากจากแหล่งข้อมูลที่แตกต่างกันและการเขียนข้อมูลใหม่เพื่อความชัดเจน สอดคล้องกัน และสมบูรณ์
- เอกสารประกอบควรอ่านเข้าใจได้ง่ายสำหรับผู้เริ่มต้น โดยไม่ต้องอุปถัมภ์ผู้ใช้ที่เชี่ยวชาญเทคโนโลยี
- วิธีสร้างพอร์ทัลเอกสารโดยใช้เครื่องมือสร้างเว็บไซต์แบบคงที่
- ไปจนถึงเอกสารสำหรับผู้ใช้ปลายทางในระยะยาวด้วยการสร้างเทมเพลตและวิธีการโดยละเอียดสำหรับผู้ร่วมให้ข้อมูลแบบโอเพนซอร์สในอนาคต
สถานการณ์ปัจจุบัน:
- เอกสารประกอบเกี่ยวกับ ScummVM ที่มีอยู่นั้นกระจายอยู่ในหลายแหล่งที่มา
- ข้อมูลค้นหาพบได้ยากและมักจะซ้ำกัน มีโอกาสหลงลืมในหน้าที่ไม่ชัดเจน
- การจะรู้ได้ว่าข้อมูลใดเป็นข้อมูลปัจจุบันและไม่เป็นปัจจุบันอะไรแล้วบ้างนั้นไม่ใช่เรื่องง่าย
- ข้อมูลบางอย่างขาดหายไปหรือไม่สมบูรณ์
การแก้ปัญหา
โครงสร้างเอกสารที่แนะนำมีดังนี้
หน้า Landing Page
|-- เริ่มต้นใช้งาน
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (แพลตฟอร์ม)
|-- การใช้ ScummVM
| |-- Launcher
| |-- การตั้งค่าส่วนกลาง
| |-- การตั้งค่าเกม
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- เพลงและเสียง
|-- ความช่วยเหลือ
| |-- คำถามที่พบบ่อย
| |-- รายชื่อติดต่อ
| |-- ปัญหาที่ทราบ
| -- Reporting a bug
|-- Game Notes-- บันทึกประจำรุ่น
- เริ่มต้นใช้งาน:
ผู้ใช้ใหม่มักจะมองหาคู่มือเริ่มใช้งานฉบับย่อเพื่อเริ่มต้นใช้งานได้อย่างรวดเร็ว แม้ว่าการติดตั้ง ScummVM อาจซับซ้อนในบางแพลตฟอร์ม แต่การติดตั้งลงในคอมพิวเตอร์ไม่ใช่เรื่องง่าย
คู่มือเริ่มใช้งานฉบับย่อควรมีข้อมูลดังต่อไปนี้
- วิธีติดตั้ง ScummVM ใน Windows, Mac และ Linux
วิธีโหลด เพิ่ม และเปิดเกม
กำลังติดตั้ง ScummVM:
ในกรณีที่การติดตั้งใช้งานยากหรือผู้ใช้อาจไม่มีฐานทางเทคนิคที่มั่นคง ผู้ใช้ต้องมีคำแนะนำที่ครอบคลุมสำหรับการติดตั้ง ScummVM ในแพลตฟอร์มที่รองรับ
หน้าการติดตั้งที่ครอบคลุมแต่ละหน้าควรครอบคลุมข้อมูลต่อไปนี้
- ข้อกำหนดของระบบ/ข้อกำหนดเบื้องต้น
- วิธีดาวน์โหลด ScummVM เวอร์ชันที่เหมาะสม
- วิธีติดตั้ง ScummVM
- วิธีโหลดเกมลงในแพลตฟอร์มที่เลือก โดยเฉพาะเมื่อไม่ใช่แพลตฟอร์มที่เกมออกแบบมา
วิธีเปิด ScummVM, เพิ่มเกม และเปิดตัวเกม
ใช้ ScummVM:
ผู้ใช้ต้องการเอกสารอ้างอิงที่อธิบายวิธีการใช้ ScummVM
เอกสารอ้างอิงควรครอบคลุมข้อมูลต่อไปนี้
- อินเทอร์เฟซ Launcher หน้าตาของแต่ละหน้าต่างและแท็บ รวมถึงวิธีการทำงาน
- คำอธิบายการตั้งค่าที่มี ทั้งส่วนกลางและเฉพาะเกม
แป้นพิมพ์ลัด/คีย์ลัด
ตัวเลือกขั้นสูง:
ผู้ใช้ขั้นสูงต้องการข้อมูลเพิ่มเติมด้านเทคนิคเพิ่มเติมเกี่ยวกับตัวเลือกต่างๆ ที่มี เพื่อปรับปรุงวิธีการทำงานของเกม
- หมายเหตุของเกม:
ข้อมูลเฉพาะเกมที่ผู้ใช้จำเป็นต้องทราบ ซึ่งรวมถึงแต่ไม่จำกัดเพียงสิ่งต่อไปนี้ - ลักษณะเฉพาะของการติดตั้ง - ต้องมีไฟล์เพิ่มเติม - มีการควบคุมผิดปกติหรือแตกต่างกัน
- ปัญหาที่เป็นที่ทราบแล้ว:
ส่วนนี้ควรมีข้อบกพร่องที่ทราบแล้วเฉพาะสำหรับรุ่นนั้นๆ
- บันทึกประจำรุ่น
แม้ว่าเอกสารของเราจะมีเวอร์ชัน แต่ส่วน "บันทึกประจำรุ่น" ก็อาจเป็นประโยชน์ในการแสดงข้อมูลสรุปการเปลี่ยนแปลงต่างๆ ในรุ่นล่าสุด ซึ่งอาจรวมถึงพื้นที่บางส่วนที่ไม่ได้อยู่ในขอบเขตของเอกสารนี้ เช่น เกมใหม่ที่รองรับหรือข้อมูลเกี่ยวกับเครื่องมือใหม่
แผนการโจมตี:
ฉันขอเสนอให้เริ่มด้วยการสร้างเทมเพลตสำหรับหน้าการติดตั้ง ScummVM เนื่องจากเป็นวิธีที่ง่ายที่สุดในการรับข้อมูลที่ต้องการจากผู้ดูแลพอร์ต/นักพัฒนาซอฟต์แวร์ (โดยเฉพาะข้อมูลที่ไม่มีข้อมูลหรือไม่มีอยู่) เราจะกรอกข้อมูลทั้งหมดที่มีอยู่แล้วจากเอกสารที่มีอยู่ ซึ่งสามารถตรวจสอบความสมบูรณ์ ความถูกต้อง และสกุลเงิน หรือเพิ่มเติมได้ตามต้องการ
ถัดไป เราจะทบทวนเอกสารที่มีอยู่ ได้แก่ README, wiki และเว็บไซต์ ในขณะทำ ฉันจะเขียนใหม่และเพิ่มในแต่ละส่วนตามที่จำเป็นและดึงข้อมูลทั้งหมดไปยังพอร์ทัลใหม่ นอกจากนี้ ฉันจะบันทึกข้อมูลที่ดึงมาจากที่ไหน เพื่อให้แน่ใจว่าเมื่อพอร์ทัลทำงานแล้ว จะไม่มีข้อมูลซ้ำซ้อน ข้อขัดแย้ง หรือความผิดปกติอื่นๆ
เราจะประสานงานกับที่ปรึกษา นักพัฒนาซอฟต์แวร์ ผู้ดูแลพอร์ต และผู้เชี่ยวชาญในด้านอื่นๆ ตลอดกระบวนการเพื่อหาข้อมูลที่หายไป รวมถึงตรวจสอบว่าหน้าเว็บแต่ละหน้ามีข้อมูลที่เป็นปัจจุบันและครอบคลุมมากที่สุด
เพื่อเป็นการส่งเสริมการทำงานร่วมกันและต้องได้รับการอนุมัติจากที่ปรึกษา ฉันจึงต้องการให้ชุมชน ScummVM เข้าถึงพอร์ทัลอยู่ระหว่างดำเนินการได้ตลอดกระบวนการเขียน เพื่อรับความคิดเห็นแบบเรียลไทม์และตรวจสอบว่าไม่มีสิ่งใดตกหล่นระหว่างทาง
เราขอแนะนำให้ใช้คู่มือสไตล์การแปล เช่น คู่มือสไตล์เอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ของ Google เพื่อให้แน่ใจว่าเนื้อหาของงานนี้มีความสอดคล้องกันและสำหรับเอกสารทั้งหมดในอนาคต
หากเป็นไปได้ ฉันจะใช้ภาพหน้าจอ, GIF และความช่วยเหลือด้านภาพอื่นๆ เพื่อเสริมสร้างความเข้าใจ
ลำดับเวลาที่เสนอ
การสานสัมพันธ์กับชุมชน 17 สิงหาคม - 13 กันยายน 2020
ใช้เวลาพูดคุยกับที่ปรึกษาและชุมชน ScummVM ในวงกว้างต่อไปเพื่อปรับวิสัยทัศน์สำหรับโครงการและสรุปรายละเอียด เช่น โครงสร้างเอกสารและเนื้อหา
สัปดาห์ที่ 1 14 กันยายน - 20 กันยายน
- สร้างเทมเพลตสำหรับหน้าการติดตั้งเฉพาะแพลตฟอร์ม
- กรอกข้อมูลที่มีอยู่ลงในเทมเพลตไว้ล่วงหน้าและเผยแพร่ไปยังผู้ดูแล/นักพัฒนาซอฟต์แวร์พอร์ตที่เหมาะสมเพื่อขอข้อมูลเพิ่มเติม
สัปดาห์ที่ 2 21 กันยายน - 27 กันยายน
- ตั้งค่าพอร์ทัลเอกสารประกอบใหม่
สัปดาห์ที่ 3 28 กันยายน - 4 ตุลาคม
การใช้ ScummVM: - อินเทอร์เฟซ - การตั้งค่าส่วนกลาง การติดตั้ง ScummVM: - คู่มือการติดตั้งเฉพาะแพลตฟอร์ม เมื่อส่งคืนเทมเพลตที่เสร็จสมบูรณ์แล้ว
สัปดาห์ที่ 4 5 ตุลาคม - 11 ตุลาคม
การใช้ ScummVM: - การตั้งค่าเกม - แป้นพิมพ์ลัด การติดตั้ง ScummVM: - คู่มือการติดตั้งเฉพาะแพลตฟอร์ม เมื่อส่งคืนเทมเพลตที่เสร็จสมบูรณ์แล้ว
สัปดาห์ที่ 5 12 ตุลาคม - 18 ตุลาคม
ตัวเลือกขั้นสูง: - Cloud และ LAN - ควบคุมการแมป การติดตั้ง ScummVM: - คู่มือการติดตั้งเฉพาะแพลตฟอร์ม เมื่อส่งคืนเทมเพลตที่เสร็จสมบูรณ์แล้ว
สัปดาห์ที่ 6 19 ตุลาคม - 25 ตุลาคม
ตัวเลือกขั้นสูง: - การกำหนดค่า - ตัวเลือกบรรทัดคำสั่ง การติดตั้ง ScummVM: - คู่มือการติดตั้งเฉพาะแพลตฟอร์ม เมื่อส่งคืนเทมเพลตที่เสร็จสมบูรณ์แล้ว
สัปดาห์ที่ 7 26 ตุลาคม - 1 พฤศจิกายน
ตัวเลือกขั้นสูง: - กราฟิก - เสียง การติดตั้ง ScummVM: - คำแนะนำในการติดตั้งเฉพาะแพลตฟอร์ม โดยส่งคืนเทมเพลตที่เสร็จสมบูรณ์ให้ฉัน
สัปดาห์ที่ 8 2 พฤศจิกายน - 8 พฤศจิกายน
ความช่วยเหลือ: - คำถามที่พบบ่อย - รายชื่อติดต่อ - ปัญหาที่เป็นที่ทราบ
การติดตั้ง ScummVM: - คู่มือการติดตั้งเฉพาะแพลตฟอร์ม เมื่อส่งคืนเทมเพลตที่เสร็จสมบูรณ์แล้ว
สัปดาห์ที่ 9 9 พฤศจิกายน - 15 พฤศจิกายน
ความช่วยเหลือ: - การรายงานข้อบกพร่อง - หมายเหตุของเกม - บันทึกประจำรุ่น
การติดตั้ง ScummVM: - สรุปคำแนะนำเกี่ยวกับแพลตฟอร์มที่ยังดำเนินการไม่เสร็จ
สัปดาห์ที่ 10 16 พฤศจิกายน - 22 พฤศจิกายน
- การแก้ไขในขั้นสุดท้าย พิสูจน์อักษร และสรุปการตัดสินใจที่เกี่ยวข้องกับพอร์ทัล เช่น การนำทางที่แถบด้านข้าง การปรับแต่งธีม/CSS ฯลฯ
- ตรวจสอบว่าลิงก์ทั้งหมดทำงานตามที่คาดไว้
- ตรวจสอบว่ารูปภาพ/GIF แสดงอย่างถูกต้อง
สัปดาห์ที่ 11 23 พฤศจิกายน - 30 พฤศจิกายน
- เตรียมสินค้าต่างๆ ที่ค้างอยู่ให้เสร็จ แล้วเปิดตัวพอร์ทัลอย่างเป็นทางการ
- เมื่อเปิดตัวพอร์ทัลแล้ว ให้นำข้อมูลที่ซ้ำซ้อนออกจากแหล่งข้อมูลอื่นๆ โดยขอคำปรึกษาจากที่ปรึกษา