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

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

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

องค์กรโอเพนซอร์ส:
โบเก้
นักเขียนเชิงเทคนิค
vis_verborum
ชื่อโปรเจ็กต์:
การสร้าง การอ่าน การแชร์: การเพิ่มประสิทธิภาพเอกสารประกอบของ Bokeh
ระยะเวลาของโปรเจ็กต์
ระยะเวลามาตรฐาน (3 เดือน)

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

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

1. บทคัดย่อ

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

กิจกรรม Season of Docs ของ 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 จะตอบคําถามของผู้ใช้อยู่เสมอ รวมถึงในบล็อก Medium ของ Bokeh

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

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

เช่น

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

3. เป้าหมาย

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

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 ยังใช้ OpenGraph เพื่อแสดงตัวอย่างลิงก์ด้วย

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

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

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

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

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

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

โดยสรุปแล้ว ผลงานที่ฉันคาดหวังจาก Season of Docs มีดังนี้

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

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

5. ไทม์ไลน์

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

ระยะการสานสัมพันธ์ในชุมชน (17/08 - 13/09):

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

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

สัปดาห์ที่ 1, 14-20 กันยายน

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

สัปดาห์ที่ 2 21/9 - 27/9

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

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

  • สรุปหลักเกณฑ์ด้านรูปแบบ
  • สรุปหน้า Landing Page ของเอกสารประกอบ

สัปดาห์ที่ 4, 5-11 ต.ค.

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

สัปดาห์ที่ 5 วันที่ 12-18 ต.ค.

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

สัปดาห์ที่ 6, 19-25 ตุลาคม

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

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

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

สัปดาห์ที่ 8, 2-8 พ.ย.

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

สัปดาห์ที่ 9, 9-15 พ.ย.

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

สัปดาห์ที่ 10, 16-22 พ.ย.

  • ดำเนินการที่เหลือให้เสร็จสมบูรณ์

สัปดาห์ที่ 11, 23-29 พ.ย.

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

ช่วงสรุปโปรเจ็กต์

สัปดาห์ที่ 12, 30 พ.ย. - 5 ธ.ค.

  • สรุปและส่งรายงานโปรเจ็กต์

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

  • สรุปและส่งการประเมินโปรเจ็กต์

หลังจากสิ้นสุด "ฤดูกาลของเอกสาร" ของ Google แล้ว

  • เราหวังเป็นอย่างยิ่งว่าจะมีส่วนร่วมในการพัฒนา Bokeh และจัดทำเอกสารประกอบของ Bokeh ต่อไป
  • เราวางแผนที่จะพัฒนาส่วนขยาย Sphinx สำหรับข้อมูลเมตา OpenGraph/Structured Data ต่อไป
  • ฉันหวังว่าจะใช้ประสบการณ์ด้านวารสารศาสตร์และเครือข่ายที่มีอยู่เพื่อโปรโมต Bokeh เป็นเครื่องมือในวารสารศาสตร์ข้อมูล เช่น เขียนเกี่ยวกับ Bokeh โดยคำนึงถึงผู้ชมที่เป็นสื่อมวลชน หรือเสนอการบรรยายในการประชุมเกี่ยวกับการใช้ 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 โดยอิงตาม docstring ที่ฉันเพิ่มลงในโค้ด

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