หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- ภาษาของจูเลีย
- ผู้เขียนด้านเทคนิค:
- mkg33
- ชื่อโปรเจ็กต์:
- เอกสารแบบรวมเกี่ยวกับแมชชีนเลิร์นนิงทางวิทยาศาสตร์
- ระยะเวลาของโปรเจ็กต์:
- วิ่งเป็นเวลานาน (5 เดือน)
คำอธิบายโปรเจ็กต์
ฉันอยากทำเรื่องการรวมองค์กร SciML ไว้เนื่องจากในส่วนนี้ยังมีอีกหลายจุดสำหรับการปรับปรุง และความสำเร็จของโปรเจ็กต์นี้จะเป็นประโยชน์ต่อทั้งโปรแกรมเมอร์ของ Julia และผู้ร่วมให้ข้อมูล/ผู้ดูแล SciML อย่างไม่ต้องสงสัย แพ็กเกจที่กระจัดกระจายอยู่ทั่วทั้ง SciML มอบเครื่องมือที่มีประโยชน์อย่างมาก แต่ก็มีอันตรายที่ผู้ใช้อาจมองไม่เห็นอยู่เสมอ (โดยเฉพาะผู้ใช้รายใหม่) เพียงเพราะผู้ใช้ไม่พบพัสดุและนำมาจัดการกับปัญหาในปัจจุบัน
เรื่องนี้น่าหงุดหงิดเนื่องจากวัตถุประสงค์หลักของแพ็กเกจคือการเข้าถึงผู้ชมโปรแกรมเมอร์ในวงกว้าง (ทั้งมือใหม่และผู้เชี่ยวชาญ) เพื่อหลีกเลี่ยงสถานการณ์ที่อธิบายข้างต้น เราขอเสนอให้แก้ไข "หน้าแรก" ของเอกสาร SciML ให้ถี่ถ้วนและสร้างฮับประเภทที่ผู้ใช้สามารถใช้เรียกดูแพ็กเกจที่เกี่ยวข้องและสำรวจระบบนิเวศที่กำลังเติบโตได้ และยังเป็นข้อมูลอ้างอิงที่มีค่าสำหรับผู้ใช้ที่มีประสบการณ์มากขึ้น และช่วยให้ทำงานได้อย่างมีประสิทธิภาพมากขึ้น
ก่อนอื่น จะต้องมีการแก้ไขเอกสารประกอบที่มีอยู่ของแต่ละแพ็กเกจทั้งหมด โดยเกี่ยวกับปัญหาพื้นฐานด้านสไตล์ (เช่น การสะกดคำ เครื่องหมายวรรคตอน ไวยากรณ์ ฯลฯ) เพื่อความสอดคล้องกันของสไตล์ SciML ต้องมีคู่มือรูปแบบที่เป็นรูปธรรม (จำเป็นอย่างยิ่งสำหรับการเปลี่ยนแปลงย้อนหลังและเพื่อใช้อ้างอิงในอนาคต) การเริ่มใหม่ตั้งแต่ต้นคงเป็นการเสียเวลา แต่ควรอิงตามแบบแผนของ Julia ที่มีอยู่และรวมเนื้อหาใหม่ทั้งหมดสําหรับปัญหา SciML โดยเฉพาะ
เมื่อคู่มือแนะนำรูปแบบเสร็จสมบูรณ์แล้ว ฉันจะแก้ไขเอกสารประกอบปัจจุบันในระยะที่ 2 ของโปรเจ็กต์ เพราะจะทำให้เอกสารดูเป็นมืออาชีพและมีความเสถียรมากขึ้น ฉันได้สร้างคำขอพุลหลายรายการที่แสดงแนวทางของฉันในงานนี้แล้ว ในระยะนี้ ข้าพเจ้ายังตั้งใจที่จะคิดค้น (และใช้งาน) ระบบการอ้างอิงที่มีประสิทธิภาพ งานแรกสุดคือการอัปเดตหน้าการอ้างอิงที่ล้าสมัย
ขั้นตอนที่ 3 หรืออาจเป็นขั้นตอนที่สำคัญที่สุดคือการออกแบบแผนกลยุทธ์ SciML ซึ่งจะเน้นการทำงานร่วมกันระหว่างพัสดุที่กระจัดกระจาย ยิ่งแพ็กเกจสองแพ็กเกจมีความสอดคล้องกันมากขึ้น (โดยพิจารณาจากตัวปัญหาหรือตัวโค้ดเอง) ก็ควรจะปรากฏในรายการ "ดูด้วย" ผมเสนอให้สร้างคีย์คำแนะนำ 2 คีย์ คีย์หนึ่งสำหรับความคล้ายคลึงของโค้ดและอีกคีย์หนึ่งสำหรับความคล้ายคลึงกันของปัญหา วิธีนี้จะช่วยให้ผู้ใช้ค้นหาแพ็กเกจอื่นๆ ที่อาจเป็นประโยชน์ได้เร็วกว่าการท่องเว็บจากที่เก็บและเอกสารที่เกี่ยวข้องนานมาก แทนที่จะแสดงรายการการเชื่อมต่อที่เป็นไปได้ทั้งหมดในแพ็กเกจ ฉันจะเน้นที่ลิงก์ที่ใหญ่กว่าและพยายามนำเสนอลิงก์ด้วยแพ็กเกจที่เล็กลง (วิธีนี้จะนำมาสู่การอัปเดตบทแนะนำในส่วนที่เกี่ยวข้องกับแพ็กเกจอื่นด้วย) วิธีการนี้ช่วยให้มั่นใจได้ว่ารายการ "ดูเพิ่มเติม" จะให้ข้อมูลโดยสังเขปของชุดค่าผสมของแพ็กเกจอย่างครบถ้วน