หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- Tor Project
- นักเขียนเชิงเทคนิค:
- Swati Thacker
- ชื่อโปรเจ็กต์:
- เขียนหน้าคู่มือของ Tor ใหม่
- ความยาวของโปรเจ็กต์:
- ดำเนินงานมาอย่างยาวนาน (5 เดือน)
คำอธิบายโปรเจ็กต์
หลังจากพูดคุยกับที่ปรึกษาของ TOR เพื่อทําความเข้าใจความคาดหวังจากโปรเจ็กต์นี้ เราขอเสนอแนวคิดต่อไปนี้เพื่อสร้างโครงสร้างและรูปแบบที่สอดคล้องกันสําหรับหน้าคู่มือ TOR (https://2019.www.torproject.org/docs/tor-manual.html.en) เพื่อเปลี่ยนให้เป็นข้อมูลอ้างอิงสั้นๆ ที่เป็นประโยชน์สําหรับผู้ใช้ โปรเจ็กต์นี้จะเสร็จสมบูรณ์ใน 3 เดือน และแนวคิดต่อไปนี้จะแบ่งตามเดือน
เดือนที่ 1
สร้างสารบัญสำหรับหน้านี้ สารบัญจะมีหัวข้อภาพรวมและส่วนหัวของตัวเลือกการกําหนดค่า 9 หมวดหมู่ทั้งหมด ภายในสิ้นเดือนนี้ ผู้ใช้จะไปยังหมวดหมู่การกําหนดค่าต่างๆ ได้อย่างรวดเร็ว ซึ่ง TOC จะมีลักษณะดังนี้
- ภาพรวม – เพิ่มข้อมูลเกี่ยวกับตำแหน่งที่ TOR เก็บรักษาการกำหนดค่าสำหรับหมวดหมู่ตัวเลือกต่างๆ เหล่านี้ หากเก็บไว้ที่เดียวกันทั้งหมด ชื่อและตำแหน่งเริ่มต้นของไฟล์การกําหนดค่า กฎในการใช้ตัวเลือกคําสั่ง และวิธีที่ผู้ใช้แก้ไขตัวเลือกเหล่านี้ได้ (เราใส่ข้อมูลจากข้อความแนะนำในส่วนหัวข้อ "รูปแบบไฟล์การกําหนดค่า" ได้)
- ตัวเลือกทั่วไป
- ตัวเลือกไคลเอ็นต์
- ตัวเลือกเซิร์ฟเวอร์
- ตัวเลือกไดเรกทอรีเซิร์ฟเวอร์
- ตัวเลือกเครือข่ายการทดสอบ
- ตัวเลือกการบรรเทาปัญหาการปฏิเสธการให้บริการ
- ตัวเลือกเซิร์ฟเวอร์ผู้ออกใบรับรอง
- ตัวเลือกบริการที่ซ่อนอยู่
- ตัวเลือกแบบคงอยู่
เดือนที่ 2:
วัตถุประสงค์ของหน้าคู่มือต้องตอบคำถามเกี่ยวกับสิ่งที่แต่ละตัวเลือกทําและวิธีทําอย่างรวดเร็ว ปัจจุบันตัวเลือกเหล่านี้ไม่ได้จัดทำเป็นเอกสารในรูปแบบที่มีโครงสร้าง และข้อมูลเกี่ยวกับแต่ละตัวเลือกจะแสดงเป็นย่อหน้า ทำให้ค้นหาข้อมูลได้ยาก ข้อมูลที่มีอยู่ทั้งหมดเกี่ยวกับตัวเลือกจะต้องได้รับการจัดระเบียบใหม่โดยใช้เทมเพลต ภายในสิ้นเดือนนี้ เราจะมีรูปแบบที่สอดคล้องกันสำหรับการบันทึกตัวเลือกที่มีอยู่และตัวเลือกใหม่ในอนาคต นอกจากนี้ รูปแบบนี้ยังช่วยให้ใช้คู่มือ TOR เป็นหน้า "man" ในอนาคตได้อย่างง่ายดาย
- ก่อนอื่น ให้เพิ่มคำอธิบายสั้นๆ เกี่ยวกับหมวดหมู่ตัวเลือกแต่ละหมวดหมู่ เช่น ตัวเลือกเซิร์ฟเวอร์ ตัวเลือกไคลเอ็นต์ และอื่นๆ คําอธิบายจะช่วยให้ผู้ใช้ทราบว่าจะมีตัวเลือกใดบ้างในแต่ละหมวดหมู่
- สร้างเทมเพลตเพื่อกําหนดรูปแบบที่สอดคล้องกันในการบันทึกตัวเลือกแต่ละรายการ เราขอแนะนำให้รวมส่วน/ส่วนย่อยต่อไปนี้ไว้ในเทมเพลต
- ชื่อ: ชื่อของตัวเลือกที่บันทึก ตัวอย่าง: BandwidthBurst
- ข้อมูลสรุป: ข้อมูลสรุปเกี่ยวกับลักษณะไวยากรณ์ของตัวเลือกในบรรทัดคำสั่ง ตัวอย่าง: BandwidthBurst N ไบต์
- คําอธิบาย: อธิบายสิ่งที่ตัวเลือกการกําหนดค่าทํา ค่าเริ่มต้นคืออะไร ตัวอย่างเช่น ใช้ตัวเลือกนี้เพื่อจํากัดขนาดสูงสุดของที่เก็บข้อมูลโทเค็น หรือที่เรียกว่าบัสท์ เป็นจํานวนไบต์ที่ระบุในแต่ละทิศทาง ตัวเลือกนี้จะมีค่าเริ่มต้นเป็น 1 GB
- ค่าตัวเลือก: แสดงรายการและอธิบายค่าที่ตัวเลือกอนุญาต อธิบายอย่างละเอียดว่าแต่ละค่าทําอะไรได้บ้างและผู้ใช้ควรป้อนค่าอย่างไร
เดือนที่ 3
ขณะนี้มีตัวเลือกการกำหนดค่า 9 กลุ่ม/หมวดหมู่ เพื่อเพิ่มความสามารถในการค้นหาและใช้อ้างอิงอย่างรวดเร็ว ให้สร้างหน้าดัชนีที่แสดงตัวเลือกการกำหนดค่าตามตัวอักษรในแต่ละหมวดหมู่ทั้ง 9 หมวดหมู่ โดยคุณสามารถเรียงลำดับหมวดหมู่เหล่านี้ตามลำดับความสำคัญของการใช้งาน โดยหมวดหมู่ตัวเลือกที่ใช้กันโดยทั่วไปจะอยู่บนสุดได้
เมื่อครบ 3 เดือน เราจะจัดทำคู่มือ TOR ฉบับปรับปรุงซึ่งผู้ใช้สามารถใช้เป็นข้อมูลอ้างอิงอย่างรวดเร็วเพื่อแก้ไขการตั้งค่าการกําหนดค่าใน TOR