หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- แหล่งข้อมูลชีววิทยาเครือข่ายแห่งชาติ (NRNB)
- นักเขียนเชิงเทคนิค:
- Prubhtej_9
- ชื่อโปรเจ็กต์:
- สร้างเอกสารประกอบสำหรับผู้ใช้สำหรับ SynBioHub และพัฒนาบทแนะนำสำหรับกรณีการใช้งานที่เฉพาะเจาะจง
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
บทคัดย่อ
เอกสารประกอบสำหรับผู้ใช้ออกแบบมาเพื่อช่วยผู้ใช้ปลายทางในการใช้ผลิตภัณฑ์หรือบริการ เอกสารประกอบที่เป็นประโยชน์สําหรับผู้ใช้มีความสําคัญมาก เนื่องจากเป็นช่องทางให้ผู้ใช้เรียนรู้วิธีใช้ซอฟต์แวร์ ฟีเจอร์ เคล็ดลับ และวิธีแก้ปัญหาที่พบได้ทั่วไปเมื่อใช้ซอฟต์แวร์ นอกจากนี้ ยังช่วยลดค่าใช้จ่ายในการสนับสนุนและเป็นส่วนหนึ่งของเอกลักษณ์ขององค์กรสำหรับผลิตภัณฑ์ด้วย กล่าวคือ เอกสารประกอบที่ยอดเยี่ยมสำหรับผู้ใช้เป็นสัญญาณบ่งชี้ว่าผลิตภัณฑ์และทีมนักพัฒนาซอฟต์แวร์มีประสิทธิภาพดี หากไม่มีเอกสารสำหรับผู้ใช้ที่ดี ผู้ใช้อาจไม่ทราบวิธีทำสิ่งต่างๆ ที่กล่าวถึงข้างต้นได้อย่างมีประสิทธิภาพและประสิทธิผล เอกสารประกอบสำหรับผู้ใช้มีบทบาทสำคัญในการทำให้ผลิตภัณฑ์ประสบความสำเร็จ เนื่องจากการสื่อสารที่ยอดเยี่ยมเป็นหัวใจสำคัญของธุรกิจหรือผลิตภัณฑ์ทุกประเภท และเอกสารประกอบที่ยอดเยี่ยมก็นำการสื่อสารนั้นมาใส่ไว้ในเฟรมเวิร์กที่สามารถจัดการได้ ซึ่งทุกคนสามารถเข้าถึงเพื่อช่วยให้ประสบความสำเร็จ SynBioHub เป็นพื้นที่เก็บข้อมูลการออกแบบสําหรับชีววิทยาสังเคราะห์ โดยมีทั้งเวอร์ชันเว็บไซต์สาธารณะและซอฟต์แวร์โอเพนซอร์ส SynBioHub ใช้ภาษาโอเพนซอร์สสำหรับแสดงการออกแบบทางพันธุกรรม (SBOL) ซึ่งเป็นมาตรฐานโอเพนซอร์สสำหรับแสดงการออกแบบทางพันธุกรรม และยังอนุญาตให้แชร์ชิ้นส่วนการออกแบบจากไฟล์ GenBank และ FASTA คุณสามารถใช้ SynBioHub เพื่อเผยแพร่คลังชิ้นส่วนและการออกแบบสังเคราะห์เป็นบริการ เพื่อแชร์การออกแบบกับผู้ทำงานร่วมกัน และเพื่อจัดเก็บการออกแบบระบบทางชีววิทยาในเครื่อง ข้อมูลใน SynBioHub สามารถเข้าถึงได้ผ่าน HTTP API, Java API หรือ Python API จากนั้นจึงผสานรวมเข้ากับเครื่องมือ CAD เพื่อสร้างการออกแบบทางพันธุกรรม SynBioHub SynBioHub มีอินเทอร์เฟซสำหรับให้ผู้ใช้อัปโหลดข้อมูลทางชีววิทยาใหม่ๆ ขึ้นไปยังฐานข้อมูล สามารถแสดงภาพส่วนต่างๆ ของ DNA, ดำเนินการค้นหาเพื่อเข้าถึงชิ้นส่วนที่ต้องการ และดาวน์โหลด SBOL, GenBank1, การใช้งานในส่วนต่างๆ ที่ต้องการ และสำหรับดาวน์โหลด SBOL, GenBank, FASTA ซึ่งมีอินเทอร์เฟซสำหรับให้ผู้ใช้อัปโหลดข้อมูลทางชีววิทยาใหม่ๆ ขึ้นไปยังฐานข้อมูล, แสดงภาพส่วนต่างๆ ของ DNA, เพื่อทำการค้นหา
สถานะปัจจุบันของเอกสาร:
ปัจจุบันเอกสารสำหรับผู้ใช้มีอยู่ที่ :"https://synbiohub.github.io/api-docs/#about-synbiohub " ซึ่งเป็นเพียงเอกสารประกอบเกี่ยวกับ API เท่านั้นและไม่มีเอกสาร GUI ซึ่งจะช่วยผู้ใช้ไปยังส่วนต่างๆ ภายในที่เก็บการออกแบบได้ นอกจากนี้ เอกสารประกอบของ API จะต้องมีการอัปเดตเล็กน้อยด้วยเช่นกัน โดยมีหัวข้อเฉพาะบางอย่าง เช่น การแก้ปัญหาเฉพาะบางอย่างที่ผู้ใช้อาจพบเจอ แม้ว่าองค์กรจะบันทึกวิดีโอแนะนำไว้บ้างแล้ว เช่น วิดีโอนี้ ไม่มีเอกสารประกอบที่เขียนขึ้นสำหรับผู้ใช้เกี่ยวกับ SynBioHub ที่จะเป็นแนวทางให้ผู้ใช้
เหตุใดเอกสารประกอบสำหรับผู้ใช้ที่คุณเสนอจึงดีกว่าเอกสารประกอบที่มีอยู่ ฉันจะสร้างเอกสาร GUI ตั้งแต่ต้นโดยใช้ GitHub และ Markdown ตามที่ที่ปรึกษาอย่างคุณ Chris Myers แนะนำ เราจะวางโครงสร้างเอกสารสำหรับผู้ใช้ที่เสนอเพื่อปรับปรุงและรับรองประสิทธิภาพ ความสอดคล้อง และความอุ่นใจให้กับผู้ใช้ปลายทางทุกคน ซึ่งจะมีคำแนะนำที่เป็นลายลักษณ์อักษรและรูปภาพที่เกี่ยวข้อง รวมถึงคำแนะนำและคำอธิบายเกี่ยวกับวิธีการใช้แต่ละฟีเจอร์ของ SynBioHub ของโปรแกรมจำลองโอเพนซอร์ส ในระหว่างการพูดคุยกับ Mr. Myers เราได้ตัดสินใจที่จะรวมเอกสารประกอบ API เข้ากับ GUI และจะมี 6 ส่วน โดยส่วนที่ 6 จะเป็นส่วนที่เลือกหรือไม่เลือกก็ได้ ส่วนต่างๆ มีดังนี้ 1. บทนำ 2. วิธีการติดตั้ง ก) จากอิมเมจที่สร้างไว้ล่วงหน้า ข) จากซอร์สโค้ด ค) การกําหนดค่า NGINX 3. วิธีการสำหรับผู้ใช้ ก) วิธีการโดยละเอียดเกี่ยวกับวิธีใช้ฟีเจอร์ GUI แต่ละรายการ ข) บทแนะนําสําหรับกรณีการใช้งานที่พบบ่อย 4. เอกสารประกอบของ API - ส่วนปลายทาง 5. เอกสารประกอบเกี่ยวกับปลั๊กอิน 6. การแก้ปัญหาและการอ้างอิงในอนาคต
Part-1:
ในส่วนนี้ ผู้ใช้จะได้รับข้อมูลเบื้องต้นโดยละเอียดและบทแนะนำต่างๆ เกี่ยวกับ SynBioHub
Part-2:
ส่วนนี้จะอธิบายวิธีต่างๆ ที่ผู้ใช้สามารถติดตั้งซอฟต์แวร์โอเพนซอร์สได้ ดังนี้ ก) จากอิมเมจที่สร้างไว้ล่วงหน้า ข) จากซอร์สโค้ด ค) การกําหนดค่า NGINX
Part-3:
นี่เป็นส่วนที่สําคัญที่สุดของเอกสารประกอบและจะใช้เวลาส่วนใหญ่ ในส่วนนี้ ระบบจะเพิ่มรายละเอียดทุกนาทีในบริบทของ GUI ดังที่กล่าวไว้ข้างต้น หลักๆ แล้วข้อกังวล 2 ประการที่จะกล่าวถึงในส่วนนี้คือคำแนะนำโดยละเอียดเกี่ยวกับวิธีใช้ฟีเจอร์ GUI แต่ละรายการและบทแนะนำสำหรับกรณีการใช้งานทั่วไป
ส่วนที่ 4:
ดังที่กล่าวไว้ข้างต้น ระบบจะใช้สเลทเพื่อสร้างเอกสารประกอบของส่วนนี้ ส่วนนี้จะรวมข้อมูลต่อไปนี้ 1. ปลายทางของผู้ใช้ 2. ปลายทางการค้นหา 3. ดาวน์โหลดอุปกรณ์ปลายทาง 4. ดาวน์โหลดอุปกรณ์ปลายทาง 5. ปลายทางการส่ง 6. จุดสิ้นสุดของสิทธิ์ 7. แก้ไขปลายทาง 8. อุปกรณ์ปลายทางของไฟล์แนบ 9. ปลายทางการดูแลระบบ
ส่วนที่ 5:
ในส่วนนี้ จะมีเอกสารประกอบของปลั๊กอินอยู่ในเอกสารประกอบเกี่ยวกับ SynBioHub แบบเก่าอยู่แล้ว ส่วนนี้จะแบ่งออกเป็น 2 ส่วน ได้แก่ ข้อกําหนดของปลั๊กอินและการใช้งาน ส่วนที่ 6: [ไม่บังคับ] ส่วนนี้จะแสดงรายการข้อผิดพลาดที่พบบ่อยซึ่งผู้ใช้พบ รวมถึงวิธีการแก้ปัญหาบางอย่าง จากที่ได้พูดคุยกับ Mr Myers ได้ลงความเห็นว่าสามารถรวมส่วนนี้เข้ากับส่วนบทนำได้หากไม่ยาวเกินไป การวิเคราะห์ คุณ Myers และฉันได้พูดคุยกันเกี่ยวกับวิธีอัปเดตเอกสารประกอบที่มีอยู่และเขียนเอกสารใหม่สำหรับ GUI ในบทสนทนา 2-3 ครั้งนี้ เราได้สร้างเลย์เอาต์พื้นฐานสำหรับเอกสารประกอบใหม่ที่กล่าวถึงข้างต้น และได้ระบุลำดับเวลาโดยประมาณไว้ในหน้า 5 ด้านล่าง ตามที่ได้พูดคุยกันไว้ เราจะใช้ github และ markdown ในการสร้างเอกสารประกอบสำหรับทุกส่วน ยกเว้นส่วนที่ 4 ของเอกสารประกอบที่จะใช้ Slate Slate:- Slate ช่วยให้คุณสร้างเอกสารประกอบของ API ที่สวยงาม ชาญฉลาด และตอบสนองได้ดี Slate เป็นเครื่องมือที่ใช้ Ruby ซึ่งสร้างเว็บไซต์เอกสารประกอบ API แบบคงที่ 3 แผงที่ดูดีเยี่ยมจากชุดไฟล์ Markdown โดยสร้างขึ้นโดยนักพัฒนาซอฟต์แวร์ Robert Lord ในปี 2013 เมื่อเขายังเป็นนักศึกษาฝึกงานอายุ 18 ปีของบริษัทซอฟต์แวร์การเดินทางอย่าง "Tripit" เขาโน้มน้าวให้เจ้านายในขณะนั้นอนุญาตให้เขาเปิดโปรเจ็กต์เป็นโอเพนซอร์ส และที่เหลือก็เป็นประวัติศาสตร์ โดย Slate มีฟีเจอร์ต่อไปนี้ • การออกแบบที่เรียบง่ายและใช้งานง่าย - เมื่อใช้ Slate คำอธิบาย API จะอยู่ที่ด้านซ้ายของเอกสารประกอบ และตัวอย่างโค้ดทั้งหมดจะอยู่ทางด้านขวา แรงบันดาลใจจากเอกสาร API ของ Stripe และ PayPal Slate ปรับเปลี่ยนตามอุปกรณ์ จึงดูดีในแท็บเล็ต โทรศัพท์ และแม้แต่สื่อสิ่งพิมพ์ • ทุกอย่างในหน้าเดียว - ยุคที่ผู้ใช้ต้องค้นหาข้อมูลในหน้าเว็บนับล้านหน้าเพื่อค้นหาสิ่งที่ต้องการนั้นจบไปแล้ว Slate จะใส่เอกสารประกอบทั้งหมดไว้ในหน้าเดียว แต่เราก็ไม่ได้ลดความสามารถในการลิงก์ เมื่อคุณเลื่อนดู แฮชของเบราว์เซอร์จะอัปเดตเป็นส่วนหัวที่อยู่ใกล้ที่สุด ดังนั้นการลิงก์ไปยังจุดใดจุดหนึ่งในเอกสารประกอบจึงยังคงทำได้อย่างง่ายดาย • Slate คือมาร์กดาวน์ - เมื่อเขียนเอกสารด้วย Slate คุณจะเขียนมาร์กดาวน์เท่านั้น ซึ่งทำให้แก้ไขและเข้าใจได้ง่าย ทุกอย่างจะเขียนเป็นมาร์กดาวน์ หรือแม้แต่ตัวอย่างโค้ดก็เป็นเพียงโค้ดบล็อกของมาร์กดาวน์ • เขียนตัวอย่างโค้ดในหลายภาษา - หาก API ของคุณมีการเชื่อมโยงในภาษาโปรแกรมหลายภาษา คุณสามารถใส่แท็บเพื่อสลับระหว่างภาษาต่างๆ ได้อย่างง่ายดาย ในเอกสาร คุณจะแยกภาษาต่างๆ ออกจากกันได้โดยระบุชื่อภาษาที่ด้านบนของบล็อกโค้ดแต่ละบล็อก เช่นเดียวกับ Markdown รูปแบบ GitHub • การไฮไลต์ไวยากรณ์ที่พร้อมใช้งานทันทีสำหรับภาษาต่างๆ กว่า 100 ภาษาโดยไม่จำเป็นต้องมีการกำหนดค่า • สารบัญที่เลื่อนผ่านได้แบบอัตโนมัติที่ลื่นไหลทางด้านซ้ายสุดของหน้า เมื่อคุณเลื่อน หน้าจอจะแสดงตำแหน่งปัจจุบันของคุณในเอกสาร รวดเร็วเช่นกัน เราใช้ Slate ที่ TripIt เพื่อสร้างเอกสารประกอบสำหรับ API ใหม่ของเรา ซึ่งสารบัญมีรายการมากกว่า 180 รายการ เราตรวจสอบแล้วว่าประสิทธิภาพยังคงยอดเยี่ยมแม้สำหรับเอกสารขนาดใหญ่ • อนุญาตให้ผู้ใช้อัปเดตเอกสารให้คุณ โดยค่าเริ่มต้น เอกสารประกอบที่ Slate สร้างขึ้นจะโฮสต์อยู่ในที่เก็บ GitHub สาธารณะ การทำเช่นนี้ไม่เพียงแต่จะให้คุณได้โฮสติ้งสำหรับเอกสารของคุณฟรีด้วย GitHub Pages เท่านั้น แต่ยังช่วยให้นักพัฒนาซอฟต์แวร์คนอื่นๆ ส่งคำขอดึงข้อมูลไปยังเอกสารของคุณได้ง่ายๆ หากพบการพิมพ์ผิดหรือปัญหาอื่นๆ แต่หากไม่ต้องการใช้ GitHub คุณก็โฮสต์เอกสารไว้ที่อื่นได้ • รองรับ RTL เลย์เอาต์แบบอ่านจากขวาไปซ้ายสำหรับภาษา RTL เช่น อาหรับ เปอร์เซีย (ฟาร์ซี) ฮิบรู ฯลฯ คำตัดสิน Slate เป็นหนึ่งในซอฟต์แวร์โอเพนซอร์สที่มีประสิทธิภาพมากที่สุดในการสร้างเอกสารประกอบ และตามที่ได้พูดคุยกับที่ปรึกษาของฉัน คุณ Chris Myers เราจะใช้ Slate สำหรับส่วนที่ 4 ส่วนส่วนอื่นๆ จะใช้ github และ markdown โปรดดูรายละเอียดเพิ่มเติมของเอกสารประกอบในส่วนด้านล่าง โครงสร้างสำหรับเอกสารประกอบที่เสนอ เราสร้างโครงสร้างสำหรับคู่มือผู้ใช้ SynBioHub ซึ่งดูได้ที่หน้า 2 โครงสร้างนี้ได้รับการยอมรับและ Mr. Myers ได้แก้ไขแล้ว เป้าหมายโปรเจ็กต์ 1. ปรับโครงสร้างเอกสารประกอบ 2. อัปเดตเอกสารประกอบให้เหมาะกับ SynBioHub เวอร์ชันใหม่ 3. นำข้อมูลที่ล้าสมัยออก 4. เขียนเอกสารประกอบสำหรับผู้ใช้ใหม่เพื่อให้เข้าใจได้ง่ายขึ้น 5. ใส่ส่วนข้อกําหนดเบื้องต้นสั้นๆ ไว้ในเอกสารประกอบสำหรับผู้มีส่วนร่วมใหม่ เพื่อเพิ่มความเข้าใจพื้นฐานเกี่ยวกับแนวคิดทางชีววิทยาพื้นฐานและอินเทอร์เฟซของ SynBioHub