หน้านี้มีรายละเอียดโครงการงานเขียนเชิงเทคนิคที่ได้รับการยอมรับใน Google Season of เอกสาร
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- CERN-HSF
- นักเขียนเชิงเทคนิค:
- Ariadne
- ชื่อโปรเจ็กต์:
- Rucio – ปรับเอกสารของ Rucio ให้ทันสมัย (ปรับโครงสร้างและเขียนใหม่)
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ข้อมูลสรุป: เฟรมเวิร์ก Rucio ได้รับการพัฒนาขึ้นเพื่อจัดการและจัดระเบียบข้อมูลทางวิทยาศาสตร์จำนวนมากที่กระจายอยู่ตามภูมิศาสตร์ในศูนย์ข้อมูลที่หลากหลาย เฟรมเวิร์กนี้มีความยืดหยุ่นสูง เป็นแบบโมดูล และขยายได้ โดยมีความสามารถต่างๆ เช่น การกู้คืนข้อมูลที่กระจายและระบบการจําลองแบบปรับเปลี่ยนได้ ผู้บริโภคเอกสารสำหรับบริการดังกล่าวจะมาจากภูมิหลังที่หลากหลายและมีข้อกำหนดที่แตกต่างกันเมื่อเข้าถึงบริการ ดังนั้น เอกสารประกอบที่ดีสำหรับบริการดังกล่าวควรช่วยให้ผู้ใช้ปลายทางใช้งานได้ง่ายขึ้น ทั้งยังใช้เป็นข้อมูลอ้างอิงสำหรับปัญหาที่พบได้ทั่วไปและการแก้ปัญหาด้วย
หากไม่มีเอกสารประกอบดังกล่าว การใช้งานอย่างมีประสิทธิภาพและประสิทธิผลจะพบกับอุปสรรคอย่างมาก ซึ่งอาจส่งผลให้มีค่าใช้จ่ายด้านการสนับสนุนเพิ่มขึ้นและก่อให้เกิดความเสี่ยงด้านชื่อเสียงต่อตัวตนขององค์กรของผลิตภัณฑ์ เอกสารประกอบเป็นรูปแบบการสื่อสารอย่างหนึ่ง การตรวจสอบว่าการสื่อสารได้รับการบรรจุไว้ในเฟรมเวิร์กที่สามารถจัดการและเข้าถึงได้ ในขณะที่ยังคงมีความเกี่ยวข้องกับเวอร์ชันที่เหมาะสม จึงเป็นการช่วยให้เราสื่อสารเพื่อความสำเร็จ
ขณะเขียนบทความนี้ เฟรมเวิร์ก Rucio กำลังถูกนำมาใช้เพื่อรองรับข้อกำหนดด้านพลังงานสูงของห้องทดลอง ATLAS และ CMS ที่ LHC นอกจากนี้ ยังใช้เพื่อตอบสนองความต้องการของชุมชนวิทยาศาสตร์ที่หลากหลายนอกเหนือจาก LHC เช่น ดาราศาสตร์ฟิสิกส์ ด้วยเหตุนี้ เอกสารจึงจำเป็นต้องมีความเกี่ยวข้องและเข้าถึงได้ง่ายที่สุด CERN ต้องการช่วยให้ผู้ใช้ปลายทางของ Rucio ได้รับประสบการณ์การใช้งานที่ราบรื่นขณะใช้เฟรมเวิร์กนี้ด้วยการแสดงมุมมองแบบรวมเพื่อเข้าถึงเอกสารประกอบที่เกี่ยวข้องทั้งหมด
สถานะปัจจุบัน: ปัจจุบันเอกสารของผู้ใช้กระจายอยู่ตามที่ต่างๆ และอยู่ในรูปแบบที่หลากหลาย ซึ่งรวมถึงบทความทางวิทยาศาสตร์, readthedocs.io ที่มีซอร์สโค้ดในโค้ด, Google ไดรฟ์, GitHub, DockerHub หรือ Wiki แหล่งที่มาหลายแห่งทำให้เกิดปัญหาในการติดตามเวอร์ชันและความถูกต้องของเอกสารประกอบ นอกจากนี้ รูปแบบเอกสารแบบกระจายอำนาจยังก่อให้เกิดอุปสรรคสำคัญในการไปยังส่วนต่างๆ และการแสดงข้อมูลที่เกี่ยวข้องสำหรับ Use Case หนึ่งๆ โดยเฉพาะอย่างยิ่งในกรณีของวิกิ ข้อมูลที่ให้ไว้สำหรับการทดสอบหนึ่งๆ อาจใช้กับอินสแตนซ์อื่นๆ ที่อยู่ในแหล่งที่มาเดียวกัน/แหล่งที่มาอื่นๆ ได้ด้วย อย่างไรก็ตาม เนื่องจากไม่มีการรวมศูนย์และการเชื่อมโยงที่เหมาะสม ข้อมูลนี้จึงไม่มีความเคลื่อนไหวและมีความเป็นไปได้ที่จะถูกใช้งานน้อยเกินไป
เหตุใดเอกสารประกอบสำหรับผู้ใช้ที่คุณเสนอจึงดีกว่าเอกสารประกอบที่มีอยู่ เนื่องด้วยปัญหาที่มีหลายแง่มุม แบบจำลองที่เสนอด้านล่างนี้จึงขจัดอุปสรรคในส่วนของการนำทาง การกำหนดเวอร์ชัน การติดตาม และการแสดงเอกสารตามรายละเอียดด้านล่าง
การปรับโครงสร้างเอกสารมีจุดประสงค์เพื่อลดความซับซ้อนในการไปยังส่วนต่างๆ สำหรับผู้ใช้ปลายทาง ผู้ชมไม่จําเป็นต้องค้นหาข้อมูลอย่างละเอียด เนื่องจากข้อมูลจะได้รับการแบ่งหมวดหมู่/ติดป้ายกำกับเพื่อความสะดวก จากมุมมองด้านการดูแลระบบ การกำหนดเวอร์ชันและการติดตามจะเป็นเรื่องง่ายเนื่องจากการปรับโครงสร้างจะให้อิสระในการจัดหมวดหมู่ตามข้อกำหนด การรวมเอกสารประกอบที่ปรับโครงสร้างใหม่ทั้งหมดไว้ในที่เดียวจะช่วยให้ผู้ใช้เห็นข้อมูลทั้งหมดได้โดยไม่ต้องไปที่แหล่งที่มาหลายแห่ง
การวิเคราะห์: หลังจากอ่านข้อมูลสรุปข้อกำหนดและพูดคุยกับทีมที่ปรึกษาแล้ว เราสรุปสถานะปัจจุบันของเอกสารประกอบของ Rucio ดังนี้
แหล่งข้อมูลหลักๆ มี 6 แห่ง ดังนี้ - ลิงก์ Google ไดรฟ์: https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs ที่ขับเคลื่อนโดย Sphinx พร้อมแหล่งที่มาในโค้ด ลิงก์ไปยังโค้ด: https://github.com/rucio/rucio ลิงก์ไปยัง ReadtheDocs: https://rucio.readthedocs.io/en/latest/
DockerHub ลิงก์: https://hub.docker.com/u/rucio
GitHub ลิงก์: https://github.com/rucio/rucio
Wiki ลิงก์: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
บทความวิทยาศาสตร์ ลิงก์: https://arxiv.org/abs/1902.09857
เอกสารประกอบจากแหล่งที่มาเหล่านี้อยู่ในรูปแบบต่างๆ เช่น Google ไดรฟ์มีเอกสารในรูปแบบสไลด์และเอกสาร, GitHub มีไฟล์เป็นภาษามาร์กอัป reStructuredText เป็นหลัก เป็นต้น ไม่มีการกำหนดเวอร์ชันและการติดตาม ทำให้มีการเผยแพร่ข้อมูลที่ซ้ำกันหลายแหล่ง การติดป้ายกำกับ/การจัดหมวดหมู่ข้อมูลนั้นไม่เท่าเทียมกัน ดังนั้นจึงต้องมีประสบการณ์และความเชี่ยวชาญก่อนหน้านี้ขณะค้นหา
รูปแบบและแหล่งที่มาที่หลากหลายทำให้ต้องจัดโครงสร้างข้อมูลใหม่และรวมไว้ในที่เดียวโดยใช้ mkdocs ผมได้ค้นคว้าและทำความคุ้นเคยกับการใช้งานเครื่องมือดังกล่าวเพื่อสร้างความเข้าใจเกี่ยวกับเครื่องมือให้ดียิ่งขึ้น
คำตัดสิน: เอกสารที่มีอยู่ไม่มีโครงสร้างและกระจัดกระจายโดยไม่มีการลิงก์ที่เหมาะสม รวมทั้งยังขาดการรวมศูนย์และการจัดรูปแบบในแบบเดียวกัน ซึ่งส่งผลให้ผู้ใช้ต้องเสียเวลามากขึ้นในการค้นหา ช่องว่างดังกล่าวยังสร้างแรงกดดันที่ไม่จำเป็นต่อผู้ดูแลระบบ/ผู้ดูแล/หัวหน้าอีกด้วย ซึ่งทำให้การบำรุงรักษาและการอัปเดตเอกสารประกอบตามแนวทางที่ขับเคลื่อนโดยชุมชนนั้นทำได้ยาก ประสบการณ์ของผู้ใช้และผู้มีส่วนร่วมจะลดลงอย่างมากและอาจเกิดซ้ำ
โครงสร้างของเอกสารประกอบที่เสนอมีดังนี้
หลังจากวิเคราะห์ข้อกําหนดอย่างละเอียดแล้ว เราตัดสินใจที่จะแก้ไขปัญหาหลักๆ ผ่านรูปแบบเอกสารประกอบที่ปรับโครงสร้างใหม่
รูปแบบที่ปรับโครงสร้างใหม่จะแสดงในภาพตัวอย่างที่แนบอยู่ด้านล่าง และจะจัดหมวดหมู่เอกสารทุกชิ้นออกเป็น 7 หมวดหมู่ต่อไปนี้
- เกี่ยวกับ
- เริ่มต้นใช้งาน
- แนวคิด
- อินเทอร์เฟซ Rucio
- งาน
- บทแนะนำ
- ความรู้ขั้นสูง
แน่นอนว่ายังมีการปรับปรุง เช่น การเพิ่มลิงก์ที่ฉันต้องการดำเนินการหลังจากจบโปรแกรมนี้ เมื่อมีผู้ใช้งานที่ใช้งานอยู่มากกว่า 1, 000 รายที่เข้าถึงข้อมูล 500 เพตาไบต์ใน Rucio การเสนอโครงสร้างใหม่ของเอกสารประกอบควรช่วยลดความจำเป็นที่ผู้ใช้จะต้องใช้รายชื่ออีเมลของทีมสนับสนุนได้อย่างมาก เป้าหมายคือปรับปรุงประสบการณ์ของผู้ใช้ให้ดียิ่งขึ้นด้วยจำนวนอัตราคลิกที่ลดลงและการแสดงเอกสารประกอบที่ง่ายดายผ่านการแบ่งหมวดหมู่และการติดป้ายกำกับ ทุกอย่างที่ผู้ใช้/เจ้าหน้าที่ปฏิบัติการ/ผู้ดูแลระบบควรทราบจะพร้อมใช้งานภายใน 3 ครั้งคลิกหรือน้อยกว่านั้น
ลิงก์โมคอัป: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
เป้าหมายโครงการ: - วิเคราะห์และตัดข้อมูลที่ซ้ำซ้อนพร้อมใช้งานจากแหล่งที่มาหลายแห่ง กล่าวคือ ข้อมูลทุกชิ้นควรมีแหล่งที่มาที่เชื่อถือได้เพียงแหล่งเดียว - ปรับโครงสร้างโดยการติดป้ายกำกับและจัดหมวดหมู่เอกสารที่มีอยู่ออกเป็นส่วนต่างๆ - ย้ายข้อมูลเอกสารที่มีการปรับโครงสร้างไปยังมุมมองแบบรวมศูนย์ตาม mkdocs - จัดรูปแบบ/นำเข้าเอกสารที่ย้ายข้อมูลไม่ได้เนื่องจากข้อจำกัดของรูปแบบไฟล์ - ตั้งค่าการแก้ไขเอกสารโดยชุมชนเพื่อให้แน่ใจว่าช่องโหว่ที่ขาดหายไปจะได้รับการเติมเต็ม ไม่ว่าจะเป็นการลิงก์ การอัปเดตข้อมูล หรือการแก้ไขข้อผิดพลาด
เรามีพื้นฐานของระบบนี้อยู่แล้ว แต่โมเดลของเราจะปรับปรุงระบบที่มีอยู่ให้ดียิ่งขึ้นด้วยการวางหลักเกณฑ์ที่เหมาะสมสำหรับการมีส่วนร่วมและการกำกับดูแลพร้อมด้วยเอกสารประกอบที่เหมาะสม นอกจากนี้ เราอยากรวมบอร์ดโปรเจ็กต์ GitHub สำหรับติดตามปัญหาและประสิทธิภาพโดยรวมของโปรเจ็กต์
ไทม์ไลน์: - ก่อนวันที่ 16 สิงหาคม --> ทำความคุ้นเคยกับเอกสารประกอบเวอร์ชันปัจจุบันและ Rucio --> เรียนรู้เทคนิคใหม่ๆ และทักษะการเขียนเชิงเทคนิคที่จะเป็นประโยชน์ในช่วงที่กำลังจัดทำโครงการ --> มีส่วนร่วมในปัญหาเกี่ยวกับเอกสาร (หากมี) จะรายงานใน GitHub
การสานสัมพันธ์ในชุมชน (17 สิงหาคม - 13 กันยายน) --> ตั้งค่าช่องทางการสื่อสารและเวลาเพื่อให้สอดคล้องกับความแตกต่างของเขตเวลา (เมืองปูเนอยู่ข้างหน้า 3 ชั่วโมง 30 นาที) --> ระบุปัญหาหลักเพื่อปรับแต่งเป้าหมาย --> ดูข้อมูลเพิ่มเติมเกี่ยวกับชุมชน องค์กร และเฟรมเวิร์กโดยการมีส่วนร่วมในการสนทนา --> การประเมินโครงสร้างเอกสารที่เสนอร่วมกับที่ปรึกษาและสมาชิกคนสำคัญคนอื่นๆ ขององค์กรเพื่อดูความเป็นไปได้และความสามารถในการติดตั้งใช้งาน --> การสรุปฟีเจอร์ที่เสนอและการแก้ไขอื่นๆ ที่จำเป็นในเอกสารประกอบที่มีอยู่
ระยะเวลาจัดทำเอกสาร (14 กันยายน - 30 พฤศจิกายน) เราได้ระบุรายละเอียดของเหตุการณ์สำคัญหลักๆ ที่วางแผนจะทำในช่วงระยะเวลาจัดทำเอกสารตามรูปแบบที่เสนอไว้ที่นี่
--> เป้าหมายที่ 1: การจัดหมวดหมู่และติดป้ายกำกับ ETC: 28 กันยายน 2020 การประเมินเอกสารประกอบที่มีอยู่และติดป้ายกำกับเอกสารเหล่านั้นจะช่วยให้กระบวนการปรับโครงสร้างและตัดเนื้อหาง่ายขึ้นมาก
--> เป้าหมายที่ 2: การวิเคราะห์ การตัดให้สั้นลง และการปรับโครงสร้าง ETC: 19 ตุลาคม 2020 เอกสารที่จัดหมวดหมู่ไว้ในเป้าหมายที่ 1 จะได้รับการวิเคราะห์เพื่อหาข้อมูลที่ซ้ำกันและซ้ำซ้อน ตามที่ได้ระบุไว้ในข้อมูลโปรเจ็กต์ เรากําลังกําหนดเป้าหมายแหล่งข้อมูลที่เชื่อถือได้แหล่งเดียวสําหรับข้อมูลทั้งหมดที่มีอยู่
--> เป้าหมายที่ 3: การรวมศูนย์และการจัดรูปแบบใหม่: ETC: 9 พฤศจิกายน 2020 เมื่อมีการตัดแต่งและปรับโครงสร้างเอกสารประกอบอย่างเหมาะสมแล้ว ฉันก็ตั้งใจจะจัดรูปแบบใหม่ก่อน รูปแบบจะแตกต่างกันไปตามแหล่งที่มาต่างๆ และต้องเปลี่ยนเป็นรูปแบบที่เหมาะสมก่อน เมื่อดำเนินการแล้ว กระบวนการรวมศูนย์จะง่ายขึ้น
--> เหตุการณ์สำคัญ #4: การตั้งค่ากระดานติดตาม + เอกสารประกอบเกี่ยวกับการจัดการ/การมีส่วนร่วม ETC: 23 พฤศจิกายน 2020 ขั้นตอนนี้มีไว้เพื่อให้มั่นใจว่าเอกสารประกอบจะได้รับการอัปเดตอย่างต่อเนื่องหลังจากโปรเจ็กต์เสร็จสมบูรณ์ การกำหนดหลักเกณฑ์และการตั้งค่ากระดานโปรเจ็กต์จะช่วยบรรเทาภาระของสมาชิกฝ่ายดูแลระบบในการขอรับผลงานจากชุมชนและติดตามผลงานเหล่านั้นได้อย่างมีประสิทธิภาพ
--> การประเมินโครงการ (30 พฤศจิกายน - 5 ธันวาคม) ส่งรายงานโครงการและการประเมินของที่ปรึกษา เขียนและส่งรายงานประสบการณ์ของฉันในฐานะผู้เข้าร่วมในซีซันของเอกสาร
เหตุผลที่ควรทำโปรเจ็กต์นี้ เราเชื่อว่าการเสริมโค้ดด้วยเอกสารประกอบที่เขียนมาอย่างดีและมีเวอร์ชันเป็นวิธีเดียวที่จะช่วยให้การนำไปใช้และการใช้งานดีขึ้น ส่วนตัวแล้ว เราหลงใหลในวิธีที่ CERN เป็นผู้นำในการวิจัยสุดล้ำในด้านฟิสิกส์ในสาขาต่างๆ ด้วยความสเกลของข้อมูลที่ประมวลผล โอน และสร้างขึ้นในระหว่างการทดสอบดังกล่าว ฉันจึงสนใจเสมอว่าองค์กรจัดการข้อมูลเพื่อใช้อ้างอิงและใช้งานในอนาคตอย่างไร เรารู้สึกเป็นเกียรติที่ได้มีส่วนร่วมในการปรับปรุงเอกสารประกอบสำหรับเฟรมเวิร์กซึ่งขับเคลื่อนการวิจัยและการค้นพบทางวิทยาศาสตร์ที่น่าทึ่ง
เหตุใดฉันจึงเหมาะกับโปรเจ็กต์นี้ นอกจากมีคุณสมบัติตรงตามข้อกําหนดเบื้องต้นแล้ว เรายังมั่นใจว่าจะเป็นบุคคลที่เหมาะสมสําหรับโปรเจ็กต์นี้ด้วยเหตุผลต่อไปนี้
เรากําลังแก้ไขเอกสารประกอบที่มีอยู่สําหรับ Kubernetes การมีส่วนร่วมเหล่านี้ส่งผลให้ฉันถูกขอให้เป็นเงาของเอกสารการเผยแพร่สำหรับรอบการเผยแพร่ Kubernetes 1.19 ซึ่งฉันมีส่วนร่วมในการรักษาและอัปเกรดเอกสารประกอบอย่างมีประสิทธิภาพสำหรับฟีเจอร์ใหม่ที่จะเพิ่มเข้ามาระหว่างการเผยแพร่ เราเชื่อว่าเอกสารประกอบที่ดีเป็นรากฐานของผลิตภัณฑ์/บริการที่ยอดเยี่ยม ข้อมูลไม่ว่าจะเกี่ยวกับขั้นตอนหรือเทคนิคก็ตาม ข้อมูลที่เขียนมาอย่างดี กระชับ และเข้าถึงได้ง่ายจะเป็นแรงกระตุ้นในการขับเคลื่อนการนำไปใช้และช่วยให้การใช้งานดีขึ้น ตลอดเส้นทางอาชีพที่ผ่านมา เราทำงานกับระบบแบบกระจายที่ขับเคลื่อนโดยข้อมูลมาโดยตลอด เราจึงเชื่อว่าเรามีความเข้าใจอย่างถ่องแท้เกี่ยวกับข้อกำหนดที่ซับซ้อนของเอกสารประกอบสำหรับระบบดังกล่าว ในฐานะผู้ใช้ปลายทาง เราคุ้นเคยกับข้อผิดพลาดของเอกสารที่เขียนไม่ดี/ไม่ถูกต้อง และจะพยายามพิจารณาข้อผิดพลาดเหล่านั้นในระหว่างการปรับโครงสร้าง