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