หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- ESLint
- ผู้เขียนด้านเทคนิค:
- คาวาร์
- ชื่อโปรเจ็กต์:
- จัดระเบียบ/เขียนเอกสารประกอบของการกำหนดค่าใหม่
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
บทคัดย่อ
เป้าหมายของโครงการนี้คือการปรับโครงสร้างเอกสารการกำหนดค่าสำหรับ ESLint ใหม่ และเพื่อสร้างสถาปัตยกรรมข้อมูลที่มีประสิทธิภาพ ซึ่งจะทำให้ไปยังส่วนต่างๆ ได้ง่ายขึ้น รวมถึงปรับปรุงความสามารถในการใช้งานและประโยชน์ของเอกสารประกอบด้วย
สรุปโครงการ เอกสารการกำหนดค่าของ ESLint (https://eslint.org/docs/user-guide/configuring) ในสถานะปัจจุบันจะแสดงข้อมูลมากมายในหน้าเว็บเดียว แม้ว่าจะมีส่วนหัว หัวข้อย่อย และย่อหน้าที่เหมาะสมในหน้า แต่เอกสารประกอบอาจเป็นได้มากเกินไป แต่ไม่มีวิธีใดที่จะไปยังส่วนใดส่วนหนึ่งของหน้าได้ ซึ่งทำให้ผู้ใช้ที่สนใจหัวข้อหนึ่งๆ รู้สึกหงุดหงิด เนื่องจากการขาดข้อมูลขององค์กรนี้ อาจทำให้ข้อมูลสูญหาย ล้มเหลวในการทำตามจุดประสงค์ และขอให้ผู้ใช้พยายามมากขึ้น
แต่ปัญหาเหล่านี้จะแก้ไขได้ด้วยขั้นตอนที่ต้องรอบคอบ เราขอเสนอการตรวจสอบเนื้อหาให้เป็นขั้นตอนแรกในการจัดระเบียบครั้งนี้ การตรวจสอบเนื้อหาไม่เพียงช่วยระบุปัญหาในการนำเสนอข้อมูล แต่ยังช่วยเน้นจุดบกพร่องของเนื้อหาด้วย (เช่น ข้อมูลที่ล้าสมัยหรือไม่ครบถ้วน) จากนั้นวางแผนจะสร้างสถาปัตยกรรมข้อมูล (Information Architecture หรือ IA) เพื่อเผยให้เห็นเครือข่ายความรู้ ซึ่งจะทำให้เราสามารถจัดกลุ่มข้อมูลตามหัวข้อต่างๆ และค้นพบความเชื่อมโยงระหว่างหัวข้อต่างๆ ที่เกี่ยวข้องอย่างใกล้ชิด ข้อมูลเชิงลึกที่ได้รับจากทั้ง 2 วิธีนี้จะนำไปแบ่งเอกสารแบบหน้าเดียวออกเป็นหลายๆ หน้า จากนั้นก็จะลิงก์ทั้งแพ็กเกจและเปรียบเทียบในมาร์กดาวน์ได้ ด้วยเหตุนี้ จึงมีเอกสารการกำหนดค่าเวอร์ชันที่มีการจัดระเบียบที่ดีขึ้น ซึ่งทำให้ไปยังส่วนต่างๆ และทำความเข้าใจได้ง่ายขึ้น
แรงจูงใจ แม้ว่าผมจะได้ใช้ซอฟต์แวร์โอเพนซอร์สมาระยะหนึ่งแล้ว แต่ฉันคุ้นเคยกับคำนี้ค่อนข้างใหม่ คล้ายกับความรู้เรื่องซอฟต์แวร์ Linting ตอนที่ผมเริ่มเรียนรู้เกี่ยวกับ Python (ผ่าน edX) ผมสงสัยว่าข้อผิดพลาดเล็กๆ น้อยๆ จะทำให้โค้ดทั้งหมดเลอะเทอะได้อย่างไร เราคิดว่าคงจะดีหากคุณได้ทดสอบโค้ดและหาข้อผิดพลาดที่พบ จากนั้นได้รู้จักคำว่า "linting" ฉันยังไม่ได้ใช้ซอฟต์แวร์ Lint อย่างเหมาะเจาะแต่ฉันมั่นใจว่าเครื่องมือเหล่านี้จะทำให้ชีวิตฉันง่ายขึ้นในวันต่อๆ ไป
ผมเป็นผู้เชี่ยวชาญด้านวิศวกรรมไฟฟ้าและประสบการณ์การเขียนโปรแกรมในระดับหนึ่ง ผมจึงเข้าใจปัญหาการเขียนโค้ดและข้อกำหนดของโปรแกรมเมอร์ได้ดีขึ้น นอกจากนี้ จบการศึกษาระดับปริญญาตรีด้านการสื่อสารทางเทคนิคและวิชาชีพจนได้เป็นผู้สนับสนุนผู้ใช้ ซึ่งพยายามทำให้ชีวิตผู้คนง่ายขึ้น ทักษะและความเชี่ยวชาญของฉันจะเป็นส่วนผสมที่ลงตัวสำหรับโครงการนี้ ซึ่งเป็นการเพิ่มคุณค่าให้กับเอกสารของ ESLint
วัตถุประสงค์ เป้าหมายโดยรวมของโครงการนี้คือ เพื่อให้มั่นใจว่าเอกสารในหน้าการกำหนดค่าของ ESLint เข้าใจง่ายและไม่ทำให้ผู้ใช้รู้สึกเหนื่อยล้า เป้าหมายสำคัญต่อความสำเร็จของโครงการก็คือการนำทางผ่านเนื้อหาสามารถทำได้โดยง่ายและปราศจากความซับซ้อน วัตถุประสงค์ที่สำคัญของโครงการมีดังนี้ - ดำเนินการตรวจสอบเนื้อหาที่ครอบคลุม - สร้างสถาปัตยกรรมข้อมูลเพื่อให้เข้าใจการรับส่งข้อมูล - ปรับปรุงสถาปัตยกรรมข้อมูลเพื่อจัดระเบียบเอกสารใหม่ - ระบุลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ของเนื้อหา - เขียนใหม่/แก้ไขส่วนต่างๆ ของเอกสาร หากจำเป็นเพื่อให้เป็นไปตามข้อกำหนดการกำหนดค่าใหม่
- ตรวจสอบให้แน่ใจว่าเนื้อหามีความยืดหยุ่นและนำกลับมาใช้ใหม่ได้
คำอธิบายโครงการ การกำหนดค่า ESLint เป็นคุณลักษณะสำคัญอย่างหนึ่งที่ทำให้ ESLint สามารถปรับแต่งได้ ผู้ใช้ที่สนใจการกำหนดค่าจะสนใจ 1 หรือ 2 แง่มุมในช่วงเวลาที่กำหนด ดังนั้น สิ่งสำคัญคือผู้ใช้ต้องถูกชี้นำไปยังหัวข้อที่สนใจเฉพาะ เพื่อนำเสนอโซลูชันด้วยวิธีที่มีประสิทธิภาพ สถานะปัจจุบันของเอกสารการกำหนดค่าสำหรับ ESLint มีข้อมูลที่เป็นประโยชน์มากมาย แต่จะได้รับการจัดระเบียบในลักษณะที่ทำให้ผู้ใช้รู้สึกเครียด หงุดหงิด และขาดหาย เช่น หากสนใจทราบข้อมูลเกี่ยวกับการใช้ปลั๊กอินของบุคคลที่สามใน ESLint ก็จะต้องเลื่อนลงไปดูเรื่องการระบุโปรแกรมแยกวิเคราะห์ สภาพแวดล้อม และ globals แนวทางปฏิบัติทั้งหมดเป็นเรื่องน่าเหนื่อยหน่ายสำหรับผู้ใช้ และอาจทำให้ผู้ใช้ออกจากเว็บไซต์ ในทำนองเดียวกัน หากผู้ใช้อยู่ตรงกลางหน้าเว็บและต้องการไปยังส่วนที่เจาะจงหรือเพียงเพื่อดูหัวข้อที่คล้ายกัน ก็ไม่ใช่เรื่องง่ายสำหรับผู้ใช้ เนื่องจากไม่มีการให้ความช่วยเหลือดังกล่าวแก่ผู้ใช้ ปัญหาเหล่านี้จำเป็นต้องได้รับการดูแลโดยทันที เนื่องจากคุณภาพของเอกสาร ไม่ว่าจะร่างไว้อย่างดีเพียงใดนั้นขึ้นอยู่กับประโยชน์ของเอกสาร เราขอเสนอวิธีแก้ไขปัญหาเหล่านี้และปัญหาอื่นๆ ที่เกี่ยวข้องในการสนทนาที่ตามมา
การตรวจสอบเนื้อหา ขั้นตอนแรกในกระบวนการจัดระเบียบเอกสารการกำหนดค่าใหม่คือการดำเนินการตรวจสอบเนื้อหาที่ครอบคลุม การตรวจสอบจะมุ่งเน้นที่การระบุปัญหาสำคัญบางอย่าง เช่น เนื้อหาที่ล้าสมัย การทำซ้ำ เนื้อหาขาดหายไป และอื่นๆ สเปรดชีตการตรวจสอบเนื้อหาที่สร้างจากผลลัพธ์จะได้รับการแชร์กับทีมการจัดการและทีมเอกสารเพื่อขอความคิดเห็น วิธีนี้จะช่วยในการคิดกลยุทธ์ใหม่ในการวางโครงสร้างและนำเสนอเอกสาร
การสร้างสถาปัตยกรรมข้อมูล การสร้างสถาปัตยกรรมสารสนเทศ (IA) อาจมีประโยชน์อย่างมากในการทำความเข้าใจเครือข่ายความรู้หรือการไหลเวียนของข้อมูลในเอกสารการกำหนดค่า ผลการตรวจสอบเนื้อหาจะใช้เป็นรากฐานที่ดีในการทำความเข้าใจและพัฒนาการไหลของข้อมูล จากนั้นระบบจะสร้าง IA เวอร์ชันปรับปรุงเพื่อจัดระเบียบและนำเสนอเอกสารให้ดีขึ้น IA ที่ปรับปรุงให้ดีขึ้นนี้ไม่เพียงแต่จะจัดโครงสร้างของเนื้อหาปัจจุบันใหม่ แต่ยังระบุลิงก์และความแตกต่างระหว่างส่วนต่างๆ ของเอกสาร เพื่อสร้างเครือข่ายที่มีประสิทธิภาพ เช่น เนื้อหาใน "การกำหนดค่ากฎ" อาจอยู่ข้างหลังด้วยลิงก์ที่นำไปยัง "การปิดใช้กฎที่มีความคิดเห็นในบรรทัด" และยังระบุลิงก์ดังกล่าวได้ ซึ่งจะสร้างความสัมพันธ์ระหว่างส่วนต่างๆ ในเอกสารประกอบ
สารบัญ การตรวจสอบเนื้อหาและ IA จะให้ข้อมูลที่เพียงพอในการสร้างสารบัญโดยละเอียดพร้อมลิงก์ไปยังส่วนที่เฉพาะเจาะจงและส่วนย่อยของเอกสาร การสร้างไฟล์แยกต่างหากสำหรับแต่ละส่วนและเพิ่มการอ้างอิงที่เหมาะสมในส่วนอื่นๆ จะช่วยเพิ่มคุณค่าให้กับเอกสารทั้งชุด ระบบจะสร้างสารบัญสำหรับผู้ใช้ไปที่เอกสารประกอบการกำหนดค่าได้ เพื่อช่วยแนะนำเส้นทางของผู้ใช้ขณะอยู่บนเว็บไซต์ สารบัญอาจมีส่วนหัวระดับที่ 1 และ 2 ทั้งหมดเพื่อให้สั้นกระชับแต่ครอบคลุม ตัวอย่างเช่น แนวทางปฏิบัติหนึ่งก็คือ Prettier (https://prettier.io/docs/en/index.html) ที่ใช้จัดระเบียบเอกสาร
ระบบจะสร้างเอกสารประกอบทั้งหมดโดยใช้มาร์กดาวน์เพื่อทำให้ทุกอย่างเรียบง่ายและเป็นระเบียบ โดยเราจะใช้ความระมัดระวังเป็นพิเศษเพื่อให้แน่ใจว่าเอกสารนํากลับมาใช้ใหม่ได้ เนื่องจากอาจขยายการใช้งานและเปลี่ยนแปลงในอนาคต
เครื่องมือสำคัญที่ใช้ได้ เครื่องมือสำคัญบางอย่างที่อาจเป็นประโยชน์ขณะทำโครงการ ได้แก่ - Draw.io สร้างภาพประกอบสำหรับ IA ที่จำเป็น - Atom (หรือเครื่องมือแก้ไขที่คล้ายกัน) สำหรับเขียนและแก้ไขเอกสารใน Markdown
- GitHub สำหรับการควบคุมเวอร์ชันของเอกสารประกอบ
เป้าหมาย ตั้งแต่การส่งข้อเสนอจนกระทั่งเสร็จสมบูรณ์ เป้าหมายเบื้องต้นต่อไปนี้จะช่วยให้มั่นใจได้ว่า โครงการจะเสร็จสิ้นตรงเวลา และคงความต่อเนื่องในกระบวนการที่ถูกต้อง
10 กรกฎาคม 2020 - 16 สิงหาคม 2020: การตรวจสอบและการเลือกข้อเสนอ ฉันจะอธิบายเอกสารของ ESLint และพัฒนาทักษะที่จำเป็นในการดำเนินโครงการให้เสร็จสิ้น (เช่น การเขียนมาร์กดาวน์, การทำงานร่วมกันใน GitHub) นอกจากนี้ ฉันจะมีส่วนร่วมในการจัดทำเอกสารผ่าน GitHub และมีส่วนร่วมกับผู้อื่นเพื่อทำความเข้าใจเอกสารประกอบให้ดียิ่งขึ้น
17 สิงหาคม 2020 - 13 กันยายน 2020: การสร้างสัมพันธ์ในชุมชน ในระหว่างระยะเวลาการสร้างความสัมพันธ์กับชุมชน ฉันจะปรับแต่งข้อเสนอตามการพูดคุยกับที่ปรึกษาและทีมที่เกี่ยวข้อง นอกจากนี้ เราจะแก้ไขวัตถุประสงค์และหลักชัยหากจำเป็น นอกจากนี้ เราจะบันทึกรายชื่อเครื่องมือที่จะใช้ในโครงการนี้
14 กันยายน 2020 - 19 กันยายน 2020: การตรวจสอบเนื้อหา เราจะดำเนินการตรวจสอบเนื้อหาของเอกสารการกำหนดค่าเพื่อเริ่มต้นโปรเจ็กต์นี้ วัตถุประสงค์คือไฮไลต์ปัญหาเกี่ยวกับเนื้อหาและการนำเสนอ
20 - 25 กันยายน 2020: สถาปัตยกรรมข้อมูล (IA) หลังจากตรวจสอบเนื้อหาแล้ว เราจะสร้าง IA ของเอกสารการกำหนดค่า ฉันจะมุ่งเน้นการนำเสนอเครือข่ายความรู้ในรูปแบบที่เข้าใจได้ ซึ่งจะช่วยในการปรับปรุงการไหลของข้อมูล
26 กันยายน 2020 - 30 กันยายน 2020: ลิงก์และข้อมูลอ้างอิง ฉันจะวิเคราะห์ IA ในระยะนี้เพื่อระบุลิงก์และข้อมูลอ้างอิงในส่วนต่างๆ ของเอกสาร นอกจากนี้ เราจะสร้างลำดับชั้นของทุกส่วนเพื่อปรับปรุง IA ในกระบวนการ
1 ตุลาคม 2020 - 3 ตุลาคม 2020: แผนที่เวอร์ชันสุดท้าย ด้วยความช่วยเหลือจากข้อมูลเชิงลึกที่ได้รับจากการตรวจสอบเนื้อหาและ IA เราจะสร้างแผนที่เวอร์ชันสุดท้ายเพื่อนำไปใช้ในเอกสารประกอบการกำหนดค่าที่จัดระเบียบใหม่ แผนที่ที่ครอบคลุมนี้จะมีสารบัญ ลำดับชั้นของหัวข้อ และรายการลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ของเอกสาร
4 ตุลาคม 2020 - 5 ตุลาคม 2020: การพูดคุย ตอนนี้ก่อนแก้ไขเอกสารประกอบ ฉันจะนำเสนอผลการศึกษาและวางแผนให้กับที่ปรึกษาและทีมที่เกี่ยวข้อง ความคิดเห็นของลูกค้าจะช่วยปรับปรุงแผนและแก้ไขตามความจำเป็น
6 ตุลาคม 2020 - 20 ตุลาคม 2020: การเขียนและแก้ไขใหม่ ในช่วงเวลานี้ เราจะแก้ไขและอัปเดตส่วนต่างๆ ของเอกสารที่ต้องมีการแก้ไข ข้อมูลบางส่วนของเอกสารการกำหนดค่าอาจมีการเขียนใหม่หรือมีการเพิ่มรายการใหม่ๆ เข้ามา จุดโฟกัสในขั้นนี้คือการตรวจสอบว่าเอกสารมีความถูกต้อง อัปเดต ยืดหยุ่น และนํากลับมาใช้ใหม่ได้
21 ตุลาคม 2020 - 25 ตุลาคม 2020: การแก้ไขและลิงก์ ในระยะนี้ ฉันจะตรวจสอบงานของฉันเองเพื่อแก้ไขข้อผิดพลาดด้านไวยากรณ์และโครงสร้าง รวมถึงตรวจสอบความถูกต้องของงานอีกครั้งด้วย นอกจากนี้เราจะเพิ่มลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ตาม IA เพื่อให้แน่ใจว่าเอกสารประกอบเป็นไปตามแผนที่ความรู้ที่คิดค้นขึ้นก่อนหน้านี้
26 ตุลาคม 2020 - 31 ตุลาคม 2020: เวอร์ชันสุดท้ายสำหรับการส่ง ฉันจะลิงก์ไฟล์มาร์กดาวน์ทั้งหมด สร้างสารบัญ และแชร์ฉบับร่างกับที่ปรึกษา ซึ่งจะเป็นการส่งฉบับร่างแรกในรูปแบบแพ็กเกจที่สมบูรณ์
1 พฤศจิกายน 2020 - 5 พฤศจิกายน 2020: การตรวจสอบครั้งแรก ในช่วง 5 วันนี้ เราจะพูดคุยเรื่องฉบับร่างแรกกับที่ปรึกษา ฉันจะรับฟังความคิดเห็นและข้อเสนอแนะจากนักเรียนเพื่อจัดทำรายการการแก้ไขที่จำเป็น
6 พฤศจิกายน 2020 - 12 พฤศจิกายน 2020: การแก้ไขครั้งแรก เราจะแก้ไขเอกสารฉบับร่างแรกโดยอาศัยความช่วยเหลือจากความคิดเห็นของที่ปรึกษา การแก้ไขที่เกิดขึ้นจริงจะขึ้นอยู่กับลักษณะของความคิดเห็น แต่วัตถุประสงค์ของการนำมาใช้ใหม่ ความถูกต้องและความยืดหยุ่นจะเป็นเหตุผลที่สำคัญในขั้นตอนการตัดต่อ
13 พฤศจิกายน 2020 - 15 พฤศจิกายน 2020: การตรวจสอบครั้งที่ 2 หลังจากที่แก้ไขเบื้องต้นเรียบร้อยแล้ว เราจะพูดคุยถึงความคืบหน้ากับที่ปรึกษาและทีมที่เกี่ยวข้องอีกครั้ง การสนทนาเหล่านี้จะมุ่งเน้นไปที่การแก้ไขเวอร์ชันแรก และเน้นย้ำถึงปัญหาอื่นๆ ที่อาจเกิดขึ้นในกระบวนการตัดต่อ
16 พฤศจิกายน 2020 - 19 พฤศจิกายน 2020: การแก้ไขครั้งที่ 2 จากนั้นเราจะแบ่งระยะเวลา 4 วันเพื่อแก้ไขเอกสารดังกล่าว เราจะหารือกับพี่เลี้ยงในเวอร์ชันต่างๆ เพื่อสร้างรูปร่างขั้นสุดท้าย เมื่อเสร็จสิ้นขั้นตอนนี้แล้ว เอกสารจะอยู่ในรูปร่างที่สมบูรณ์ ซึ่งพร้อมที่จะอัปโหลดไปยังเว็บไซต์และที่เก็บ GitHub
20-23 พฤศจิกายน 2020: การอัปโหลดบนเว็บไซต์ หลังจากแก้ไขที่จำเป็นทั้งหมดแล้ว ระบบจะอัปโหลดเอกสารไปยังเว็บไซต์ ปัญหาใดๆ ที่พบในกระบวนการนี้จะได้รับการจัดการตามลําดับเนื่องจากเราจะยังเหลือเวลา 2-3 วันในการแก้ไข
24 พฤศจิกายน 2020 - 28 พฤศจิกายน 2020: รายงานโปรเจ็กต์ ระบบจะสร้างรายงานโดยละเอียดเกี่ยวกับโปรเจ็กต์ในระยะเวลา 5 วันนี้ ทั้งนี้ วัตถุประสงค์ ปัญหา ปัญหา และวิธีแก้ปัญหาที่นำเสนอจะเป็นส่วนหนึ่งของรายงานโครงการ ระบบจะแชร์รายงานกับ Mentor เพื่อขอความคิดเห็น
29 พฤศจิกายน 2020 - 30 พฤศจิกายน 2020: การส่งโครงการครั้งสุดท้าย ระบบจะส่งรายงานโปรเจ็กต์พร้อมไฟล์ทั้งหมดและรายงานโปรเจ็กต์ให้ที่ปรึกษา การตรวจสอบทั้งโครงการจะดำเนินการผ่านการประชุม/หารือกับที่ปรึกษาและทีมที่เกี่ยวข้อง
ตลอดโปรเจ็กต์ ฉันจะปรึกษากับ Mentor ต่อไปเพื่อให้ได้รับความคิดเห็นที่เป็นประโยชน์ เป้าหมายทั้งหมดนี้สามารถปรับเปลี่ยนได้โดยขึ้นอยู่กับการพูดคุยกับ Mentor ในช่วงสร้างความสนิทสนมในชุมชนและช่วงตรวจสอบข้อเสนอ
เกี่ยวกับฉัน ฉันสำเร็จการศึกษาระดับปริญญาตรีสาขาวิศวกรรมไฟฟ้า และสำเร็จการศึกษาระดับปริญญาโทด้านการสื่อสารทางเทคนิคและวิชาชีพจากมหาวิทยาลัยนอร์ทแคโรไลนาสเตต ฉันมีประสบการณ์ในด้านการเขียนและการแก้ไขทางเทคนิคและวิชาชีพ การสื่อสารและการจัดการเนื้อหา การศึกษาความสามารถในการใช้งานบนเว็บและอุปกรณ์เคลื่อนที่ และการออกแบบการสอน ฉันเคยทำงานเป็น Sub-Editor ให้กับสื่อเผยแพร่ออนไลน์ (Global Village Space) และเป็น Communications Intern ให้กับ Duke Forge ที่มหาวิทยาลัย Duke นอกจากนั้น ฉันยังสนใจการเขียนเชิงสร้างสรรค์ด้วย