โครงการ CERN-HSF

หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs

ข้อมูลสรุปของโปรเจ็กต์

องค์กรโอเพนซอร์ส:

CERN-HSF

ผู้เขียนด้านเทคนิค:

อารียาดเน

ชื่อโปรเจ็กต์:

Rucio – ปรับเอกสารของ Rucio ใหม่ (ปรับโครงสร้างและเขียนใหม่)

ระยะเวลาของโปรเจ็กต์:

ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

นามธรรม: กรอบการทำงาน Rucio พัฒนาขึ้นโดยมีมุมมองในการจัดการและจัดระเบียบข้อมูลทางวิทยาศาสตร์แบบกระจายทางภูมิศาสตร์ในศูนย์ข้อมูลที่มีความหลากหลาย เฟรมเวิร์กนี้มีความสามารถที่หลากหลาย เช่น การกู้คืนข้อมูลแบบกระจายและการจำลองที่ปรับเปลี่ยนได้ ผู้บริโภคที่มีเอกสารประกอบสำหรับบริการดังกล่าวจะมาจากภูมิหลังที่แตกต่างกันและมีข้อกำหนดที่แตกต่างกันเมื่อเข้าถึง ดังนั้น เอกสารประกอบที่ดีสำหรับบริการดังกล่าวจึงควรช่วยลดความซับซ้อนในการนำไปใช้และการนำไปใช้งานสำหรับผู้ใช้ปลายทาง ในขณะเดียวกันก็เป็นข้อมูลอ้างอิงสำหรับปัญหาที่พบได้ทั่วไปและการแก้ไขปัญหาด้วย

หากไม่มีเอกสารประกอบดังกล่าว อาจสร้างอุปสรรคสำคัญในการใช้งานอย่างมีประสิทธิภาพและประสิทธิผล ซึ่งอาจทำให้ค่าใช้จ่ายในการสนับสนุนเพิ่มขึ้นและก่อให้เกิดความเสี่ยงต่อเอกลักษณ์องค์กรของผลิตภัณฑ์ ในท้ายที่สุด เอกสารก็คือรูปแบบการสื่อสารอย่างหนึ่ง การทำให้การสื่อสารครอบคลุมอยู่ในเฟรมเวิร์กที่จัดการได้และเข้าถึงง่าย ขณะเดียวกันก็ยังคงมีความเกี่ยวข้องโดยมีการกำหนดเวอร์ชันที่เหมาะสม จึงเป็นการรับรองว่าเรากำลังสื่อสารเพื่อความสำเร็จ

ขณะที่เขียนบทความนี้ ได้มีการนำเฟรมเวิร์กของ Rucio มาใช้ในการขับเคลื่อนข้อกำหนดด้านพลังงานสูงของการทดลอง ATLAS และ CMS ที่ LHC นอกจากนี้ยังมีการใช้งานเพื่อสนับสนุนความต้องการของชุมชนวิทยาศาสตร์ที่หลากหลายนอกเหนือจาก LHC เช่น ฟิสิกส์ดาราศาสตร์ด้วย จึงทำให้เอกสารมีความเกี่ยวข้องและเข้าถึงได้มากที่สุด โครงการนี้ทำให้ CERN ต้องการช่วยให้ผู้ใช้ปลายทางของ Rucio ใช้งานได้อย่างลื่นไหล ขณะเดียวกันก็ใช้เฟรมเวิร์กด้วยการแสดงมุมมองแบบรวมศูนย์ในการเข้าถึงเอกสารที่เกี่ยวข้องทั้งหมด

สถานะปัจจุบัน: นับจนถึงปัจจุบัน เอกสารสำหรับผู้ใช้มีการเผยแพร่ไปในที่ต่างๆ และในหลายรูปแบบ ได้แก่ บทความทางวิทยาศาสตร์, readthedocs.io ที่มีซอร์สในโค้ด, Google ไดรฟ์, GitHub, DockerHub หรือ Wiki แหล่งข้อมูลหลายแห่งทำให้เกิดปัญหาในการติดตามเวอร์ชันและความถูกต้องของเอกสาร นอกจากนี้ รูปแบบเอกสารแบบกระจายศูนย์ยังเป็นอุปสรรคสำคัญในการนำทางและการแสดงข้อมูลที่เกี่ยวข้องสำหรับกรณีการใช้งานนั้นๆ โดยเฉพาะอย่างยิ่งในกรณีของ Wiki ข้อมูลที่ให้ไว้สำหรับการทดสอบหนึ่งๆ อาจนำไปประยุกต์ใช้กับกรณีอื่นๆ ที่อยู่ในแหล่งข้อมูลเดียวกัน/อื่นได้เช่นกัน อย่างไรก็ตาม เนื่องจากไม่มีการรวมข้อมูลและลิงก์ที่เหมาะสม ข้อมูลนี้จึงไม่มีความเคลื่อนไหวและอาจนำไปใช้ประโยชน์ได้น้อยเกินไป

เหตุใดเอกสารสำหรับผู้ใช้ที่คุณเสนอจึงได้รับการปรับปรุงมากกว่าเอกสารปัจจุบัน จากปัญหาแบบหลายแง่มุม โมเดลที่เสนอด้านล่างจึงช่วยลดอุปสรรคในการนำทาง การกำหนดเวอร์ชัน การติดตาม และการนำเสนอเอกสารประกอบตามรายละเอียดด้านล่าง:

การปรับโครงสร้างเอกสารประกอบมีจุดประสงค์เพื่อลดความซับซ้อนในการไปยังส่วนต่างๆ ของผู้ใช้ปลายทาง เขา/เธอไม่จำเป็นต้องลงไปตามรูกระต่ายขณะที่ค้นหาข้อมูล เนื่องจากข้อมูลจะได้รับการจัดหมวดหมู่/ติดป้ายกำกับเพื่อให้เข้าใจง่าย ในมุมมองด้านการดูแลระบบ การกำหนดเวอร์ชันและการติดตามจะทำได้อย่างง่ายดาย เนื่องจากการปรับโครงสร้างจะให้อิสระในการจัดหมวดหมู่ได้ตามความต้องการ การรวมเอกสารที่มีโครงสร้างทั้งหมดไว้ที่ส่วนกลางจะทำให้ผู้ใช้สามารถดูข้อมูลทั้งหมดได้โดยไม่ต้องดูแหล่งข้อมูลหลายๆ แห่ง

การวิเคราะห์: หลังจากอ่านข้อความคร่าวๆ เกี่ยวกับข้อกำหนดและพูดคุยกับทีมที่ปรึกษาแล้ว ข้อมูลการหักเงินจากสถานะปัจจุบันของเอกสาร Rucio มีดังต่อไปนี้

เอกสารมีแหล่งที่มาหลัก 6 แหล่ง ได้แก่ - ลิงก์ Google ไดรฟ์ : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

• Readthedocs ที่ขับเคลื่อนโดย Sphinx โดยมีซอร์สในโค้ด ลิงก์ไปยังโค้ด: https://github.com/rucio/rucio ลิงก์ไปยัง ReadtheDocuments: https://rucio.readthedocs.io/en/latest/

• DockerHub ลิงก์: https://hub.docker.com/u/rucio

• GitHub Link: https://github.com/rucio/rucio

• ลิงก์ Wiki: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasdistributiondComputing

• บทความวิทยาศาสตร์ ลิงก์: 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)

เป้าหมายของโครงการ: - วิเคราะห์และตัดข้อมูลที่ซ้ำกันจากแหล่งต่างๆ กล่าวคือ ข้อมูลทุกชิ้นควรมีแหล่งข้อมูลที่เชื่อถือได้เพียงแหล่งเดียว - ปรับโครงสร้างโดยการติดป้ายกำกับและจัดหมวดหมู่เอกสารที่มีอยู่ออกเป็นส่วนต่างๆ - ย้ายเอกสารประกอบการปรับโครงสร้างไปยังมุมมองแบบรวมศูนย์ตามเอกสาร - จัดรูปแบบ/นำเข้าเอกสารใหม่ที่ไม่สามารถย้ายข้อมูลได้เนื่องจากข้อจำกัดรูปแบบไฟล์ - ตั้งค่าการแก้ไขเอกสารจากชุมชนเพื่อให้มั่นใจว่าช่องว่างที่หายไปได้รับการเติมเต็ม โดยในแง่ของการเชื่อมโยง การอัปเดตข้อมูล หรือการแก้ไขข้อผิดพลาด

ชุดโค้ดสำหรับระบบนี้พร้อมให้ใช้งานแล้ว แต่โมเดลของฉันจะปรับปรุงระบบที่มีอยู่โดยวางหลักเกณฑ์ที่เหมาะสมในการมีส่วนร่วมและการกำกับดูแลพร้อมเอกสารประกอบที่เหมาะสม นอกจากนี้ ผมอยากใช้กระดานโปรเจ็กต์ GitHub เพื่อติดตามปัญหาและประสิทธิภาพการทำงานโดยรวมของโปรเจ็กต์

ไทม์ไลน์: - ก่อนวันที่ 16 สิงหาคม --> ทำความคุ้นเคยกับเอกสารประกอบเวอร์ชันปัจจุบันและ Rucio --> เรียนรู้เทคนิคใหม่ๆ และทักษะการเขียนเชิงเทคนิคที่จะเป็นประโยชน์ในช่วงเปิดโครงการ --> ร่วมแก้ไขปัญหาเกี่ยวกับเอกสารประกอบ (หากมี) ที่รายงานใน GitHub

• ความผูกพันกับชุมชน (17 สิงหาคม - 13 กันยายน) --> ตั้งช่องทางและเวลาในการสื่อสารเพื่อให้คำนึงถึงความแตกต่างของเขตเวลา (Pune ใช้เวลาล่วงหน้า 3 ชั่วโมง 30 นาที) --> ระบุประเด็นปัญหาหลักๆ ที่นำไปสู่การปรับแต่งเป้าหมาย --> ดูข้อมูลเพิ่มเติมเกี่ยวกับชุมชน องค์กร และกรอบการทำงานด้วยการมีส่วนร่วมในการสนทนา --> การประเมินโครงสร้างเอกสารประกอบที่เสนอร่วมกับพี่เลี้ยงและสมาชิกหลักคนอื่นๆ ขององค์กรเกี่ยวกับความสามารถในการทำงานและความเป็นไปได้ในการนำไปปฏิบัติ --> การสรุปฟีเจอร์ที่เสนอและการแก้ไขอื่นๆ ที่อาจต้องทำในเอกสารที่มีอยู่

• ระยะเวลาจัดทำเอกสาร (14 กันยายน - 30 พฤศจิกายน) ตามรูปแบบที่นำเสนอในที่นี้ เราได้แจกแจงเหตุการณ์สำคัญที่วางแผนจะบรรลุในช่วงระยะเวลาที่จัดทำเอกสารไว้

--> เป้าหมายที่ 1: การจัดหมวดหมู่และติดป้ายกำกับ ETC: 28 กันยายน 2020 การประกอบเอกสารประกอบที่มีและติดป้ายกำกับจะช่วยลดความซับซ้อนของกระบวนการปรับโครงสร้างและตัดทอนลงได้มาก

--> เป้าหมายที่ 2: การวิเคราะห์ การตัดทอน และปรับโครงสร้าง ETC: 19 ตุลาคม 2020 เอกสารที่ได้รับการจัดหมวดหมู่ในเหตุการณ์สำคัญข้อ 1 จะได้รับการวิเคราะห์เพื่อหาข้อมูลที่ซ้ำกันและแหล่งที่มาซ้ำซ้อน ตามที่ระบุในข้อมูลโปรเจ็กต์ เรากําหนดเป้าหมายแหล่งข้อมูลที่เชื่อถือได้เพียงแหล่งเดียวสําหรับข้อมูลทั้งหมดที่มีอยู่

--> เป้าหมายที่ 3: การรวมศูนย์และการจัดรูปแบบใหม่: ETC: 9 พฤศจิกายน 2020 เมื่อปรับแต่งและปรับโครงสร้างเอกสารประกอบอย่างเหมาะสมแล้ว เราจะตั้งเป้าที่ที่จะจัดรูปแบบเอกสารใหม่ก่อน เนื่องจากมีแหล่งที่มาที่หลากหลาย รูปแบบจึงแตกต่างกันและจำเป็นต้องเปลี่ยนรูปแบบให้เป็นรูปแบบที่เหมาะสมก่อน เมื่อทำเสร็จแล้ว กระบวนการรวมศูนย์จะง่ายขึ้น

--> เป้าหมายที่ 4: การตั้งค่ากระดานติดตาม + เอกสารประกอบเกี่ยวกับการกำกับดูแล/เงินสนับสนุน ETC: 23 พฤศจิกายน 2020 ระยะนี้เพื่อให้แน่ใจว่าหลังจากสิ้นสุดโปรเจ็กต์แล้ว เอกสารยังคงมีการอัปเดตอยู่เรื่อยๆ การวางแนวทางและตั้งค่ากระดานโครงการจะช่วยลดภาระให้กับสมาชิกฝ่ายธุรการในการขอความช่วยเหลือจากชุมชนและติดตามแผนงานได้อย่างมีประสิทธิภาพ

--> การประเมินโครงการ (30 พฤศจิกายน - 5 ธันวาคม) ส่งรายงานโครงการและประเมินที่ปรึกษา เขียนและส่งรายงานประสบการณ์จากการเป็นผู้เข้าร่วมใน Season of Docs

ทำไมต้องมีโครงการนี้ ฉันเชื่อว่าการเสริมโค้ดด้วยเอกสารประกอบที่เขียนขึ้นอย่างดีและมีเวอร์ชันเป็นวิธีการเดียวที่จะทำให้มีการนำไปใช้ต่อไปและการใช้งานที่ดีขึ้น โดยส่วนตัวแล้ว ผมหลงใหลวิธีที่ CERN เป็นผู้บุกเบิกการวิจัยที่ล้ำสมัยในสาขาฟิสิกส์ต่างๆ เนื่องด้วยปริมาณของข้อมูลที่ประมวลผล โอน และสร้างขึ้นระหว่างการทดลองดังกล่าว ฉันจึงรู้สึกสนใจวิธีการจัดการข้อมูลเพื่อการอ้างอิงและการใช้งานในองค์กรในอนาคต เรารู้สึกยินดีอย่างยิ่งที่ได้มีส่วนร่วมในการปรับปรุงเอกสารประกอบสำหรับกรอบการทำงานที่เป็นพลังขับเคลื่อนการวิจัยและการค้นพบทางวิทยาศาสตร์อันน่าทึ่ง

เหตุใดฉันจึงเป็นบุคคลที่เหมาะสมสำหรับโครงการนี้ นอกจากการปฏิบัติตามข้อกำหนดเบื้องต้นแล้ว ฉันมั่นใจว่าจะเป็นบุคคลที่เหมาะสมสำหรับโปรเจ็กต์นี้ตั้งแต่:

ฉันกำลังแก้ไขเอกสารประกอบที่มีอยู่แล้วสำหรับ Kubernetes การสนับสนุนเหล่านี้ทำให้ฉันได้รับสิทธิ์ให้เป็นเงาเอกสารการเผยแพร่สำหรับรอบการเผยแพร่ Kubernetes เวอร์ชัน 1.19 ซึ่งฉันจะมีส่วนร่วมในการดูแลรักษาและอัปเกรดเอกสารอย่างมีประสิทธิภาพสำหรับฟีเจอร์ใหม่ที่มีเพิ่มเข้ามาระหว่างการเผยแพร่ ฉันเชื่อว่าเอกสารประกอบที่ดีเป็นหัวใจสำคัญของผลิตภัณฑ์/บริการที่ยอดเยี่ยม ข้อมูลที่เขียนขึ้นมาอย่างดี กระชับ และเข้าถึงง่ายจะเป็นข้อมูลเชิงขั้นตอนหรือด้านเทคนิค เป็นแรงผลักดันในการผลักดันให้เกิดการนำไปใช้และช่วยให้ใช้งานได้ดียิ่งขึ้น ฉันได้ทำงานกับระบบแบบกระจายที่ขับเคลื่อนด้วยข้อมูลตลอดสายอาชีพ ฉันเชื่อว่าตนเองอยู่ในจุดที่เข้าใจความสลับซับซ้อนในข้อกำหนดเกี่ยวกับเอกสารสำหรับระบบดังกล่าวได้ดีที่สุด หลังจากได้เป็นผู้ใช้ปลายทางแล้ว ฉันคุ้นเคยกับหลุมพรางต่างๆ ของเอกสารที่เขียนได้ไม่ดี/ไม่ถูกต้อง และจะต้องคำนึงถึงข้อผิดพลาดดังกล่าวระหว่างการปรับโครงสร้าง