โปรเจ็กต์โบเก้

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

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

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

โบเก้

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

vis_verborum

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

การสร้าง การอ่าน และการแชร์: การเพิ่มประสิทธิภาพเอกสารประกอบของ Bokeh

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

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

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

การสร้าง การอ่าน และการแชร์: การเพิ่มประสิทธิภาพเอกสารประกอบของ Bokeh

1. บทคัดย่อ

Bokeh เป็นเครื่องมือที่มีประสิทธิภาพมากในการสร้างการแสดงภาพแบบอินเทอร์แอกทีฟบนเบราว์เซอร์ด้วย Python โดยมีฐานผู้ใช้ขนาดใหญ่ (การดาวน์โหลด Conda รายเดือน 502,000 ครั้ง, การดาวน์โหลด PyPi 855,000 ครั้ง) และมีผู้ร่วมให้ข้อมูลจำนวนมาก (ผู้ร่วมให้ข้อมูล 455 รายใน GitHub) จึงไม่น่าแปลกใจที่เอกสารประกอบที่มีเนื้อหามากมายของ Bokeh จะเติบโตขึ้นเรื่อยๆ และด้วยเหตุนี้ ในที่ต่างๆ มีความไม่แน่นอน เข้าถึงยาก และซับซ้อน

เทศกาลอ่านเอกสารของ Google มอบโอกาสที่ไม่เหมือนใครสำหรับการตรวจสอบและแก้ไขโครงสร้างและเนื้อหาในเอกสารประกอบของ Bokeh อย่างเข้มข้น และช่วยให้มั่นใจว่าเอกสารประกอบรวมถึงเครื่องมือและเวิร์กโฟลว์ที่เกี่ยวข้องจะประสบความสำเร็จในอนาคต

ฉันเขียนโค้ดและจัดทำโปรเจ็กต์โอเพนซอร์สด้วย Python และ Sphinx (ล่าสุดคือ PyZillow และ PyPresseportal) แต่สิ่งที่ทำให้ฉันรู้สึกไม่เหมือนใครใน Season of Docs ของ Google คือความเป็นมาในวงการข่าวของฉัน ฉันทำงานในห้องข่าวมานานกว่า 13 ปี และเป็นบรรณาธิการที่จัดการและสนับสนุนการเปลี่ยนแปลงในโลกดิจิทัล นอกจากหน้าที่ด้านการนำเสนอข่าวแล้ว ฉันยังเพิ่มความรับผิดชอบในการออกแบบและจัดทำเอกสารเกี่ยวกับเครื่องมือดิจิทัลและคำแนะนำสไตล์ใหม่ๆ รวมถึงการฝึกอบรมพนักงานในสำนักข่าวด้วย

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

2. สถานการณ์ปัจจุบัน

เอกสารอย่างเป็นทางการของ Bokeh ประกอบด้วยหน่วยงานหลักต่อไปนี้

• เอกสารประกอบการบรรยาย: คู่มือการติดตั้ง คู่มือผู้ใช้ คู่มือนักพัฒนาซอฟต์แวร์ บันทึกประจำรุ่น
• แกลเลอรีและการสาธิต (ตัวอย่างแบบอินเทอร์แอกทีฟพร้อมซอร์สโค้ด)
• คู่มืออ้างอิง (เอกสารประกอบเกี่ยวกับสตริงเอกสาร)
• บทแนะนำ (คอลเล็กชันมากมายของสมุดบันทึก Jupyter ที่โฮสต์ใน mybinder.org)
• เอกสารและความช่วยเหลือเกี่ยวกับโมเดลสำหรับ IDE
• ตัวอย่างและ README ในที่เก็บโปรเจ็กต์

นอกจากนี้ยังมีข้อมูลมากมายในฟอรัมการสนับสนุนของ Bokeh และใน Stack Overflow ซึ่งนักพัฒนาของ Bokeh ยังคอยตอบคำถามของผู้ใช้อย่างแข็งขัน รวมถึงในบล็อก Bokeh ของ Medium ด้วย

หน้าเว็บเอกสารประกอบส่วนใหญ่จะสร้างด้วย Sphinx โดยใช้ส่วนขยาย Sphinx แบบมาตรฐานและที่กำหนดเองหลายรายการ ตัวอย่างเช่น คู่มืออ้างอิงจะสร้างขึ้นจาก docstring ซึ่งใช้ส่วนขยาย เช่น "autodoc" และ "bokeh_autodoc" ที่กำหนดเอง ตามลักษณะของเอกสารที่เติบโตแบบออร์แกนิก จึงมีความซ้ำซ้อนและไม่สอดคล้องกัน

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

เช่น

• การใช้คำนาม กลุ่มคำนาม และคำที่ไม่นิยมใช้แทนคำกริยาที่ชัดเจนและหนักแน่นจะทำให้ข้อความบางส่วนมีความซับซ้อนโดยไม่จำเป็น "ข้อสังเกตหลักก็คือการใช้งานโดยทั่วไปจะเกี่ยวข้องกับการสร้างวัตถุพล็อตด้วยฟังก์ชันตัวเลข()" ซึ่งควรปรับรูปแบบเพื่อให้อ่านง่ายขึ้น เช่น "ฟังก์ชันตัวเลข() เป็นฟังก์ชันที่ใช้กันมากที่สุดเพื่อสร้างวัตถุพล็อต"
• บางประโยคยาวมากจนทำให้เข้าใจยาก: "ต่อไปเราสามารถเรียก vbar ด้วยรายการปัจจัยชื่อผลไม้เป็นพิกัด x ความสูงของแท่งเป็นพิกัดด้านบน และทางเลือกความกว้างหรือคุณสมบัติอื่นๆ ที่เราต้องการ" ประโยคที่ยาวขึ้นควรแบ่งออกเป็นประโยคสั้นๆ หรือรายการสัญลักษณ์หัวข้อย่อย การปรับรูปประโยคให้ง่ายขึ้นจะเป็นประโยชน์อย่างยิ่งสำหรับผู้ใช้ที่เป็นโรคดิสเล็กเซียหรือคนที่ไม่ได้ใช้ภาษาอังกฤษเป็นภาษาแรก (ดูปัญหา #10160)
• การใช้คำว่า "คุณ" และ "เรา" อย่างไม่สอดคล้องกันซึ่งสร้างความสับสนและรบกวน เช่น "มี 2 วิธีพื้นฐานที่ใช้ได้ ขึ้นอยู่กับกรณีการใช้งานของคุณ" และ "เราสามารถพล็อตซีรีส์ตลอดทั้งปีโดยใช้การโทรแยกกัน" (2 ตัวอย่างจากหน้าเดียวกัน) บางหน้าระบุตัวอ่านด้วยวิธีที่ต่างกันไป เช่น "ผู้ใช้อาจต้องติดตั้ง Dependencies เพิ่มเติม" หรือ "ผู้ใช้อาจสร้างเลย์เอาต์ที่ซับซ้อนขึ้นได้"
• การพิมพ์ผิด คำที่ไม่มีความหมายและคำที่ไม่จำเป็น รวมถึงข้อผิดพลาดด้านไวยากรณ์จะแยกขั้นตอนการอ่านและทำลายความน่าเชื่อถือของข้อมูล เช่น "โบเก้ทำให้สร้างแผนภูมิแท่งพื้นฐานได้ง่ายๆ" หรือ "ดูส่วนอักขระในคู่มือผู้ใช้"
• ความไม่สอดคล้องกันของโครงสร้างอาจทำให้ผู้อ่านรู้สึกหงุดหงิด เช่น การมีตัวอย่างพร้อมคำอธิบายประกอบที่ชัดเจนในหน้าหนึ่ง และไม่มีคำอธิบายของตัวอย่างในหน้าอื่น

หน้า Landing Page ของเอกสารของ Bokeh ค่อนข้างสั้นและไม่มีข้อมูลเกี่ยวกับแหล่งข้อมูลทั้งหมดที่มี (ไม่มีการกล่าวถึงไลบรารีเอกสารจำนวนมากและฟังก์ชันความช่วยเหลือของโมเดล ฟอรัมการสนับสนุน การสาธิต หรือบล็อก Medium) และยังทำให้ผู้ใช้ใหม่เริ่มต้นใช้งาน Bokeh ได้ยากขึ้นด้วย

3. ยิงประตู

ในการใช้ระยะ 11 สัปดาห์ในการพัฒนาเอกสารให้มีประสิทธิภาพมากที่สุด ฉันจะเน้นองค์ประกอบหลัก 3 อย่าง ได้แก่

3.1. ปรับปรุงการสร้างเอกสาร

เอกสารประกอบส่วนใหญ่ของ Bokeh เขียนขึ้นโดยผู้ให้ข้อมูลร่วมกันซึ่งมีเอกสารประกอบเป็นส่วนหนึ่งของการดึงคำขอฟังก์ชันการทำงานใหม่ๆ และการแก้ไขข้อบกพร่อง แม้ว่าช่วงนี้เราจะใช้ช่วงการพัฒนาเอกสารบางช่วงเพื่อแก้ไขและปรับโครงสร้างเอกสารที่มีอยู่ใหม่ แต่ฉันขอเน้นย้ำว่าขั้นตอนในการสร้างและรักษาเอกสารให้พร้อมสู่อนาคต: ซึ่งควรจะง่ายที่สุดที่ผู้ให้ข้อมูลจะมีความสม่ำเสมอในการจัดทำเอกสารมาตรฐานที่สูงอย่างต่อเนื่อง

ฉันจะตรวจสอบได้ด้วย 2 วิธีต่อไปนี้

• ฉันจะสร้างชุดหลักเกณฑ์รูปแบบที่ใช้งานง่ายและนำไปใช้ได้จริงเพื่อรวมไว้ในคู่มือนักพัฒนาซอฟต์แวร์ที่มีอยู่ หลักเกณฑ์เหล่านี้จะกล่าวถึงรูปแบบ ไวยากรณ์ และโครงสร้าง นอกจากนี้ เราจะใช้ช่องทางการสื่อสารภายใน เช่น Slack เพื่อให้ผู้มีส่วนร่วมของ Bokeh ทราบถึงหลักเกณฑ์ด้านสไตล์ นอกจากนี้ เรายังจะมีการฝึกอบรมแบบตัวต่อตัวและเซสชันถามและตอบสำหรับทีมอีกด้วย
• เราจะทำงานร่วมกับทีมหลักเพื่อหาชุดเครื่องมือที่เหมาะสมสำหรับการควบคุมคุณภาพเอกสาร ซึ่งจะเพิ่มลงในเวิร์กโฟลว์ที่มีอยู่ของ Bokeh สำหรับ PR (คำขอแบบพุล) และ CI (การผสานรวมอย่างต่อเนื่อง) ซึ่งอาจหมายถึงการเพิ่มเครื่องมือ เช่น pydocstyle, proselint หรือการสะกดคำแบบ sphinxcontrib ลงในชุดทดสอบของ Bokeh, การตั้งค่าแบบผูกมัด หรือการดำเนินการบน GitHub ทั้งนี้ขึ้นอยู่กับข้อกำหนดของทีม ฉันได้เพิ่มการพิสูจน์แนวคิดที่ใช้งานได้ลงในการดำเนินการใน GitHub ของหนึ่งในโปรเจ็กต์โอเพนซอร์สของฉันเอง

3.2. ปรับปรุงการอ่านเอกสาร

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

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

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

เช่นเดียวกับการปรับปรุงการสร้างเอกสารที่ระบุไว้ข้างต้น ฉันจะมุ่งเน้นไปที่การวางรากฐานสำหรับการปรับปรุงในอนาคตและมาตรฐานระดับสูงอย่างต่อเนื่องสำหรับเอกสารประกอบของ Bokeh

3.3. ปรับปรุงการแบ่งปันเอกสาร

ปัจจุบันมีการพูดคุยเกี่ยวกับ Bokeh มากขึ้นบนแพลตฟอร์มของบุคคลที่สาม แพลตฟอร์มเหล่านี้จำนวนมากใช้ข้อมูลเมตา เช่น OpenGraph ของ Facebook เพื่อใส่ตัวอย่างลิงก์แบบละเอียด บริการต่างๆ เช่น Facebook, Twitter, LinkedIn, Slack และ iMessage จะใช้ OpenGraph ฟอรัม Discourse ของ Bokeh ยังใช้ Open Graph ในการแสดงผลตัวอย่างลิงก์ด้วย

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

และยังสร้างข้อพิสูจน์แนวคิดที่ประสบความสำเร็จในการใช้ในโปรเจ็กต์โอเพนซอร์ส PyPresseportal ของฉันด้วย ส่วนขยายนี้จะรวบรวมข้อมูลที่เกี่ยวข้องโดยอัตโนมัติ เช่น ชื่อ คำอธิบาย รูปภาพ และ URL จากนั้นจึงแทรกข้อมูลนี้ลงในโค้ด HTML ที่สฟิงซ์สร้างขึ้นเป็นแท็ก OpenGraph

ขั้นตอนต่อไปในการพัฒนาส่วนขยายนี้คือการแนะนำคำสั่งที่กำหนดเองเพื่อกำหนดข้อมูลเมตา OpenGraph ด้วยตนเอง (คล้ายกับคำสั่ง ‘meta’ ที่มีอยู่ของ docutil) ข้อมูลเมตาที่สร้างขึ้นโดยอัตโนมัติจะใช้เป็นโฆษณาสำรองเท่านั้นในกรณีที่ไม่มีข้อมูลที่ป้อนด้วยตนเอง

การรองรับข้อมูลที่มีโครงสร้างนั้นซับซ้อนกว่ามาก ดังนั้นฉันจะเน้นใส่ข้อมูลเมตา Open Graph คุณภาพสูงในเอกสารประกอบของ Bokeh เป็นหลัก งานทั้งหมดที่ส่งเสริม OpenGraph จะช่วยวางรากฐานสำหรับการรองรับข้อมูลที่มีโครงสร้างไปพร้อมกัน

สมาชิกของชุมชน Sphinx และ ReadTheDocs ได้แสดงความสนใจในการพัฒนาส่วนขยายสำหรับ OpenGraph และข้อมูลที่มีโครงสร้าง (เช่น ในฉบับ #1758 และ #5208) และเราจะทำงานร่วมกับพวกเขาอย่างใกล้ชิด

4. สิ่งที่ส่งมอบ

โดยสรุปแล้ว นี่คือสิ่งที่เราคาดว่าจะได้รับจากซีซันของเอกสาร:

• หลักเกณฑ์รูปแบบการจัดทำเอกสารสำหรับผู้ร่วมให้ข้อมูลโบเก้
• แก้ไขเวิร์กโฟลว์ PR และ CI ให้มีการควบคุมคุณภาพของเอกสารแบบอัตโนมัติ
• คู่มือผู้ใช้ที่แก้ไขแล้วและปรับโครงสร้าง
• หน้า Landing Page ของเอกสารที่มีการแก้ไข
• ข้อมูลเมตาของ Open Graph ที่อยู่ในหน้าเว็บเอกสารและส่วนขยาย Sphinx ที่ใช้งานได้

นอกจากนี้ ฉันจะเก็บ “doclog” เพื่อบันทึกเส้นทางการเดินทางในฤดูกาลของเอกสารของ Google บนเว็บไซต์ส่วนตัว/Medium หรือบล็อก Medium ของ Bokeh ซึ่งจะใช้เป็นพื้นฐานสำหรับรายงานโครงการสำหรับ Google ด้วย ฉันจะทำงานทั้งหมดอย่างโปร่งใสในรูปแบบของปัญหา GitHub และดึงคำขอเมื่อเป็นไปได้

5. ไทม์ไลน์

ก่อนช่วงสร้างความสนิทสนมกับชุมชน: ฉันมีส่วนร่วมในการสนทนามากมายเกี่ยวกับที่เก็บ GitHub ของ Bokeh อยู่แล้วและได้ติดต่อกับ Bryan Van de Ven และ Pavithra Eswaramoorthy ซึ่งเป็นที่ปรึกษาของ Bokeh สำหรับ Season of Docs ของ Google ฉันจะติดตามการสนทนาเกี่ยวกับ Bokeh ต่อไปและยังทำความคุ้นเคยกับ Bokeh ด้วยการสร้างและเผยแพร่การแสดงภาพ

ระยะสร้างความผูกพันกับชุมชน (17/08 - 13/09):

• ทำความรู้จักทีมหลัก ปรับแต่งแผนโครงการเพื่อแลกเปลี่ยนกับที่ปรึกษา
• จัดตารางเวลาและช่องทางการสื่อสารสำหรับการรายงานและการแสดงความคิดเห็นกับที่ปรึกษาเป็นประจำ
• ใช้งาน Slack ของ Bokeh อยู่เสมอเพื่อแจ้งให้ผู้ร่วมให้ข้อมูล Bokeh ที่สนใจทุกคนทราบเกี่ยวกับฤดูกาลของ Google เอกสารและเป้าหมายสำหรับระยะการพัฒนาเอกสาร
• รวบรวมความคิดเห็นจากผู้ร่วมให้ข้อมูลที่ใช้ Bokeh เพื่อปรับปรุงแผนสำหรับระยะการพัฒนาเอกสารเพิ่มเติม

ระยะการพัฒนาเอกสาร

สัปดาห์ที่ 1, 14/09 - 20/09:

• เริ่มการตรวจสอบและแก้ไขเอกสารประกอบการบรรยาย
• เริ่มร่างหลักเกณฑ์รูปแบบ

สัปดาห์ที่ 2, 21/09 - 27/09:

• ดำเนินการต่อเกี่ยวกับหลักเกณฑ์ด้านรูปแบบ
• แก้ไขเอกสารการบรรยายต่อ
• เริ่มปรับเปลี่ยนหน้า Landing Page ของเอกสารใหม่

สัปดาห์ที่ 3, 28/09 - 04/10:

• สรุปหลักเกณฑ์ด้านสไตล์
• สรุปหน้า Landing Page ของเอกสาร

สัปดาห์ที่ 4, 5/10 - 11/10:

• แก้ไขเอกสารประกอบคำบรรยายให้เสร็จสิ้น
• พูดคุยกับทีมหลักของ Bokeh เกี่ยวกับการผสานรวมเครื่องมือสำหรับการควบคุมคุณภาพของเอกสารในเวิร์กโฟลว์ PR/CI

สัปดาห์ที่ 5, 12/10 - 10/10:

• จัดเซสชันถามและตอบกับผู้ร่วมให้ข้อมูล Bokeh ใน Slack เพื่อพูดคุยเกี่ยวกับหลักเกณฑ์สไตล์ การปรับปรุงเอกสารประกอบการบรรยาย และเวิร์กโฟลว์ PR/CI
• เริ่มพัฒนาการพิสูจน์แนวคิดที่มีอยู่สำหรับข้อมูลเมตา OpenGraph ให้เป็นส่วนขยาย Sphinx ที่ทำให้ใช้งานได้
• แก้ไขหลักเกณฑ์ด้านสไตล์โดยอิงตามความคิดเห็นจากเซสชันถามและตอบกับ Contributor ของ Bokeh

สัปดาห์ที่ 6, 19/10 - 25/10:

• เริ่มการทดสอบเครื่องมือสำหรับการควบคุมคุณภาพของเอกสารในเวิร์กโฟลว์ PR และ CI
• พัฒนาส่วนขยาย Sphinx สำหรับข้อมูลเมตาต่อ

สัปดาห์ที่ 7, 26/10 - 01/11:

• การทดสอบส่วนขยาย Sphinx
• เซสชันถามและตอบครั้งที่ 2 กับผู้ร่วมให้ข้อมูล Bokeh ใน Slack
• แก้ไขสิ่งที่ส่งมอบตามความคิดเห็นจากเซสชันถามและตอบครั้งที่ 2

สัปดาห์ที่ 8, 02/11 - 08/11:

• ใช้งานส่วนขยาย Sphinx และเผยแพร่เอกสารประกอบการบรรยายและหน้า Landing Page เอกสารที่ปรับปรุงใหม่

สัปดาห์ที่ 9, 09/11 - 15/11:

• นำเครื่องมือควบคุมคุณภาพของเอกสารไปใช้ในเวิร์กโฟลว์ PR และ CI
• อัปเดตและเผยแพร่คู่มือนักพัฒนาซอฟต์แวร์เพื่อระบุหลักเกณฑ์ด้านสไตล์และส่วนเพิ่มเติมเกี่ยวกับเวิร์กโฟลว์ PR และ CI

สัปดาห์ที่ 10, 16/11 - 22/11:

• ทำงานที่เหลือให้เสร็จ

สัปดาห์ที่ 11, 23/11 - 29/11:

• เริ่มเขียนรายงานโครงการ
• เริ่มเขียนการประเมินโปรเจ็กต์

ระยะสรุปโปรเจ็กต์

สัปดาห์ที่ 12, 30/11 - 5/12:

• ทำให้สิ้นสุดและส่งรายงานโปรเจ็กต์

สัปดาห์ที่ 13, 12/12 - 10/12:

• ดำเนินการขั้นสุดท้ายและส่งการประเมินโปรเจ็กต์

หลังจากสรุปฤดูกาลของเอกสารของ Google:

• ฉันหวังว่าจะได้มีส่วนร่วมในการพัฒนาโบเก้และจัดทำเอกสารประกอบของ Bokeh ต่อไป
• ฉันวางแผนที่จะพัฒนาส่วนขยาย Sphinx สำหรับข้อมูลเมตาของ OpenGraph/ข้อมูลที่มีโครงสร้าง ต่อไป
• ฉันต้องการใช้ภูมิหลังในการนำเสนอข่าวและเครือข่ายที่มีอยู่เพื่อโปรโมต Bokeh เป็นเครื่องมือในการทำข่าวด้วยข้อมูล เช่น เขียนเกี่ยวกับโบเก้โดยเน้นที่ผู้ชมข่าว หรือเสนอการพูดคุยเกี่ยวกับการใช้โบเก้ในสภาพแวดล้อมการนำเสนอข่าว

6. เกี่ยวกับตัวฉันเอง

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

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

ขออภัยที่คู่มือและเอกสารที่ฉันเขียนในงานก่อนหน้านี้ไม่ได้เผยแพร่ต่อสาธารณะ ดังนั้น ตอนนี้ฉันจึงมุ่งเน้นไปที่การมีส่วนร่วมมากขึ้นกับโครงการโอเพนซอร์ส (ดูตัวอย่างด้านล่าง) ฉันศึกษางานเขียนทางเทคนิคเกี่ยวกับคู่มือสไตล์ต่างๆ เช่น คู่มือสไตล์เอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ของ Google และคู่มือสไตล์การเขียนของ Microsoft ฉันใช้ GitHub, Slack และ Linux เป็นประจำ ผมได้เขียนเอกสารประกอบการบรรยาย รวมทั้งสตริงเอกสารและคำแนะนำการพิมพ์โดยใช้เครื่องมือต่างๆ เช่น Sphinx, Mypy และ Sphinx autodoc

ตอนนี้ฉันเป็นฟรีแลนซ์ ตารางเวลาของฉันให้ความยืดหยุ่นที่จำเป็นในการทำงานในเอกสารของ Bokeh ประมาณ 25 ชั่วโมงต่อสัปดาห์ในช่วงการพัฒนาเอกสาร ฉันทำงานในเขตเวลาแปซิฟิก แต่ยินดีที่จะอำนวยความสะดวกด้านกำหนดการและความต้องการของทีม

7. ตัวอย่างเอกสารโอเพนซอร์สล่าสุด

• PyZillow: PyZillow คือ Wrapper ของ Python สำหรับ API ของเว็บไซต์อสังหาริมทรัพย์ Zillow.com นอกจากให้โค้ดบางอย่างและทำหน้าที่เป็นหนึ่งในผู้ดูแลโค้ดแล้ว เรายังได้เขียนเอกสารประกอบฉบับสมบูรณ์ไว้ ฉันใช้ Sphinx สำหรับใช้เป็นเอกสารประกอบการบรรยายและสำหรับการอ้างอิงโมดูล ฉันสร้างการอ้างอิงโมดูลด้วย autodoc ของส่วนขยาย Sphinx ตามสตริงเอกสารที่ฉันเพิ่มลงในโค้ด

• PyPresseportal: PyPresseportal คือ Wrapper ของ Python สำหรับ API ของเว็บไซต์ presseportal.de เว็บไซต์ presseportal.de เป็นหนึ่งในผู้เผยแพร่เนื้อหาข่าวประชาสัมพันธ์และประกาศความสัมพันธ์ของนักลงทุนที่ใหญ่ที่สุดในเยอรมนี ตัวอย่างเช่น ตำรวจและหน่วยดับเพลิงเกือบทั้งหมดที่ใช้บริการนี้เพื่อกระจายข่าวประชาสัมพันธ์ หลังจากใช้ API นี้ในฐานะนักข่าวมาหลายปี ฉันตัดสินใจที่จะพัฒนาอินเทอร์เฟซ Python เพื่อเข้าถึงแหล่งข้อมูลขนาดใหญ่ของเว็บไซต์ในฐานะวัตถุของ Python ฉันเขียนโค้ดและเอกสารประกอบทั้งหมดที่อิงตาม Sphinx