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