หน้านี้มีรายละเอียดโครงการงานเขียนเชิงเทคนิคที่ได้รับการยอมรับใน Google Season of เอกสาร
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- ESLint
- นักเขียนเชิงเทคนิค
- Khawar
- ชื่อโปรเจ็กต์:
- จัดระเบียบ/เขียนเอกสารประกอบเกี่ยวกับการกําหนดค่าใหม่
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
บทคัดย่อ
เป้าหมายของโปรเจ็กต์นี้คือการปรับโครงสร้างเอกสารประกอบเกี่ยวกับการกำหนดค่าสำหรับ ESLint และสร้างสถาปัตยกรรมข้อมูลอย่างมีประสิทธิภาพ ซึ่งจะช่วยให้ไปยังส่วนต่างๆ ได้ง่ายขึ้น ทั้งยังช่วยปรับปรุงความสามารถในการใช้งานและความมีประโยชน์ของเอกสารประกอบ
สรุปโปรเจ็กต์ เอกสารประกอบเกี่ยวกับการกําหนดค่าของ ESLint (https://eslint.org/docs/user-guide/configuring) ในปัจจุบันมีข้อมูลจํานวนมากในหน้าเดียว แม้จะมีส่วนหัว ส่วนหัวย่อย และการแบ่งย่อหน้าที่เหมาะสมในหน้า แต่เอกสารประกอบก็อาจดูน่าสับสนได้ ไม่มีวิธีไปยังส่วนเฉพาะของหน้า ซึ่งทำให้ผู้ใช้ที่สนใจส่วนนั้นรู้สึกหงุดหงิด ข้อมูลอาจสูญหายเนื่องจากไม่มีการจัดระเบียบ ทำให้ไม่เป็นไปตามวัตถุประสงค์และทำให้ผู้ใช้ต้องพยายามมากขึ้น
อย่างไรก็ตาม ปัญหาเหล่านี้สามารถแก้ไขได้ด้วยขั้นตอนต่างๆ ที่ต้องทำอย่างระมัดระวัง ฉันเสนอการตรวจสอบเนื้อหาเป็นขั้นตอนแรกในการจัดระเบียบใหม่ การตรวจสอบเนื้อหาไม่เพียงช่วยระบุปัญหาในการนำเสนอข้อมูล แต่ยังช่วยเน้นให้เห็นข้อบกพร่องของเนื้อหาด้วย (เช่น ข้อมูลล้าสมัยหรือไม่สมบูรณ์) จากนั้นเราวางแผนที่จะสร้างสถาปัตยกรรมข้อมูล (IA) เพื่อเปิดตัวเครือข่ายความรู้ ซึ่งจะทำให้เราสามารถจัดกลุ่มข้อมูลตามหัวข้อต่างๆ และสามารถค้นหาความเชื่อมโยงระหว่างหัวข้อต่างๆ ที่เกี่ยวข้องอย่างมากได้ จากนั้นจะนำข้อมูลเชิงลึกที่ได้จากแนวทางปฏิบัติทั้ง 2 วิธีนี้ไปใช้แบ่งเอกสารหน้าเดียวออกเป็นหลายหน้า จากนั้นจะลิงก์และแลกเปลี่ยนข้อมูลแพ็กเกจทั้งแพ็กเกจในมาร์กดาวน์ ด้วยเหตุนี้ เอกสารประกอบเกี่ยวกับการกําหนดค่าจึงมีเวอร์ชันที่จัดระเบียบได้ดียิ่งขึ้น ใช้งานและเข้าใจได้ง่ายขึ้น
แรงจูงใจ แม้ว่าฉันจะใช้ซอฟต์แวร์โอเพนซอร์สมาเป็นเวลานานแล้ว แต่ฉันเพิ่งคุ้นเคยกับคำว่า "โอเพนซอร์ส" ไม่นานมานี้ เช่นเดียวกับความรู้เกี่ยวกับซอฟต์แวร์ Linting เมื่อเริ่มเรียน Python (ผ่าน edX) ฉันสงสัยว่าข้อผิดพลาดเล็กๆ น้อยๆ จะทำให้โค้ดทั้งโค้ดพังได้อย่างไร เราคิดว่าการทดสอบโค้ดและระบุข้อผิดพลาดน่าจะเป็นเรื่องดี แล้วเราก็ได้รู้จักคำว่า "Linting" เรายังไม่ได้ใช้ซอฟต์แวร์ดังกล่าวอย่างเหมาะสม แต่เรามั่นใจว่าสิ่งเหล่านี้จะช่วยให้ชีวิตเราง่ายขึ้นมากในอนาคต
พื้นฐานด้านวิศวกรรมไฟฟ้าและประสบการณ์การเขียนโปรแกรมบางส่วนช่วยให้ฉันเข้าใจปัญหาการเขียนโค้ดและข้อกำหนดของนักเขียนโปรแกรมได้ดียิ่งขึ้น นอกจากนี้ การศึกษาระดับปริญญาโทด้านการสื่อสารทางเทคนิคและวิชาชีพยังทำให้ฉันเป็นผู้สนับสนุนผู้ใช้และพยายามทำให้ชีวิตผู้คนง่ายขึ้น ทักษะและความเชี่ยวชาญของฉันจะเป็นส่วนผสมที่ลงตัวสำหรับโครงการนี้ และช่วยเพิ่มมูลค่าให้กับเอกสารประกอบเกี่ยวกับ ESLint
วัตถุประสงค์ เป้าหมายโดยรวมของโครงการนี้คือเพื่อให้มั่นใจว่าเอกสารในหน้าการกำหนดค่าของ ESLint จะเข้าใจได้ง่ายและไม่รบกวนผู้ใช้ การนำทางไปยังส่วนต่างๆ ของเนื้อหาต้องง่ายและไม่ซับซ้อนเพื่อให้โปรเจ็กต์ประสบความสำเร็จ วัตถุประสงค์ที่สําคัญของโครงการมีดังนี้ - ดำเนินการตรวจสอบเนื้อหาอย่างครอบคลุม - สร้างสถาปัตยกรรมข้อมูลเพื่อทำความเข้าใจการไหลของข้อมูล - ปรับปรุงสถาปัตยกรรมข้อมูลเพื่อจัดระเบียบเอกสารประกอบใหม่ - ระบุลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ของเนื้อหา - เขียน/แก้ไขเอกสารประกอบบางส่วน หากจำเป็นเพื่อให้เป็นไปตามข้อกำหนดในการกำหนดค่าใหม่
- ตรวจสอบว่าเนื้อหามีความยืดหยุ่นและนํามาใช้ซ้ำได้
คำอธิบายโปรเจ็กต์ การกำหนดค่า ESLint เป็นฟีเจอร์สำคัญที่ทำให้ ESLint ปรับแต่งได้ ผู้ใช้ที่สนใจการกำหนดค่าจะสนใจด้านใดด้านหนึ่งหรือสองด้าน ณ เวลาหนึ่งๆ อย่างแน่นอน ดังนั้น การนำผู้ใช้ไปยังหัวข้อที่สนใจจึงมีความสำคัญเพื่อให้ผู้ใช้ได้รับวิธีแก้ปัญหาอย่างมีประสิทธิภาพ สถานะปัจจุบันของเอกสารการกำหนดค่าสำหรับ ESLint มีข้อมูลที่เป็นประโยชน์มากมาย แต่ได้รับการจัดระเบียบในลักษณะที่ทำให้ผู้ใช้รู้สึกเครียด หงุดหงิด และสับสนได้ ตัวอย่างเช่น หากผู้ชมสนใจที่จะเรียนรู้เกี่ยวกับการใช้ปลั๊กอินของบุคคลที่สามใน ESLint จะต้องเลื่อนลงเพื่อดูการพูดคุยเกี่ยวกับการระบุโปรแกรมแยกวิเคราะห์ สภาพแวดล้อม และตัวแปรส่วนกลาง กระบวนการทั้งหมดนี้ทำให้ผู้ใช้เหนื่อยหน่ายและอาจทำให้ผู้ใช้ออกจากเว็บไซต์ ในทำนองเดียวกัน หากผู้ใช้อยู่บริเวณตรงกลางของหน้าและต้องการไปที่ส่วนหนึ่งๆ หรือเพียงแค่ดูหัวข้อที่คล้ายกัน ก็คงไม่ใช่เรื่องง่ายสำหรับผู้ใช้ เนื่องจากไม่ได้ให้ความช่วยเหลือดังกล่าวแก่ผู้ใช้ ปัญหาเหล่านี้ต้องได้รับการแก้ไขโดยทันที เนื่องจากคุณภาพของเอกสารประกอบไม่ว่าจะร่างมาได้ดีเพียงใดก็ขึ้นอยู่กับความมีประโยชน์ของเอกสาร ฉันเสนอวิธีแก้ปัญหาเหล่านี้และปัญหาอื่นๆ ที่เกี่ยวข้องในการพูดคุยที่ตามมา
การตรวจสอบเนื้อหา ขั้นตอนแรกในกระบวนการจัดระเบียบเอกสารการกําหนดค่าใหม่คือการดําเนินการตรวจสอบเนื้อหาอย่างครอบคลุม การตรวจสอบจะมีจุดประสงค์เพื่อระบุปัญหาสำคัญบางประการ เช่น เนื้อหาล้าสมัย เนื้อหาซ้ำกัน เนื้อหาขาดหายไป เป็นต้น สเปรดชีตการตรวจสอบเนื้อหาที่สร้างขึ้นจากผลการตรวจสอบจะแชร์กับทีมการจัดการและทีมเอกสารประกอบเพื่อรับความคิดเห็น ซึ่งจะช่วยในการหากลยุทธ์ใหม่ในการจัดโครงสร้างและนำเสนอเอกสารประกอบ
การสร้างสถาปัตยกรรมข้อมูล การสร้างสถาปัตยกรรมสารสนเทศ (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 และฝึกทักษะที่จำเป็นเพื่อทำให้โปรเจ็กต์เสร็จสมบูรณ์ (เช่น การเขียน Markdown, การทำงานร่วมกันใน GitHub) นอกจากนี้ เรายังจะมีส่วนร่วมในเอกสารประกอบผ่าน GitHub และมีส่วนร่วมกับผู้อื่นเพื่อให้เข้าใจเอกสารประกอบได้ดียิ่งขึ้น
17 สิงหาคม 2020 - 13 กันยายน 2020: ทำความรู้จักกับชุมชน ในระหว่างช่วงทำความรู้จักกับชุมชน ฉันจะปรับแต่งข้อเสนอตามที่ได้พูดคุยกับที่ปรึกษาและทีมที่เกี่ยวข้อง รวมถึงแก้ไขวัตถุประสงค์และเหตุการณ์สำคัญด้วยหากจำเป็น นอกจากนี้ เราจะเลือกเครื่องมือที่จะใช้กับโปรเจ็กต์ให้ด้วย
14-19 กันยายน 2020: การตรวจสอบเนื้อหา ในการเริ่มต้นโปรเจ็กต์ เราจะทำการตรวจสอบเนื้อหาที่ครอบคลุมของเอกสารประกอบเกี่ยวกับการกำหนดค่า โดยมีวัตถุประสงค์เพื่อไฮไลต์ปัญหาเกี่ยวกับเนื้อหาและการแสดงเนื้อหา
20 กันยายน 2020 - 25 กันยายน 2020: สถาปัตยกรรมสารสนเทศ (IA) หลังจากการตรวจสอบเนื้อหา ฉันจะสร้าง IA ของเอกสารประกอบการกำหนดค่า เราจะมุ่งเน้นที่การนำเสนอเครือข่ายความรู้ในลักษณะที่เข้าใจง่าย ซึ่งจะช่วยปรับปรุงการไหลของข้อมูล
26 กันยายน 2020 - 30 กันยายน 2020: ลิงก์และการอ้างอิง เราจะวิเคราะห์ IA ในระยะนี้เพื่อแมปลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ของเอกสารประกอบ เราจะสร้างลําดับชั้นของส่วนทั้งหมดด้วย ซึ่งจะช่วยปรับปรุง IA ในกระบวนการนี้
วันที่ 1-3 ตุลาคม 2020: แผนที่สุดท้าย เราจะสร้างแผนที่สุดท้ายเพื่อนำไปใช้ในเอกสารการกําหนดค่าที่จัดระเบียบใหม่ด้วยข้อมูลเชิงลึกที่ได้จากการสํารวจเนื้อหาและ IA แผนที่ที่ครอบคลุมนี้จะมีสารบัญ ลําดับชั้นของหัวข้อ และรายการลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ของเอกสารประกอบ
4 ตุลาคม 2020 - 5 ตุลาคม 2020: การสนทนา ในจุดนี้ เราจะนำเสนอสิ่งที่พบและวางแผนให้กับที่ปรึกษาและทีมที่เกี่ยวข้องก่อนที่จะแก้ไขเอกสาร ความคิดเห็นของพวกเขาจะช่วยในการปรับแต่งแผนและทำการเปลี่ยนแปลงที่จำเป็น
6-20 ตุลาคม 2020: เขียนและแก้ไขใหม่ ในระหว่างนี้ เราจะแก้ไขและอัปเดตส่วนต่างๆ ของเอกสารที่ต้องดำเนินการ เอกสารการกำหนดค่าบางส่วนอาจมีการเขียนใหม่หรือมีการเพิ่มข้อมูลใหม่ลงไป โดยจะเน้นการตรวจสอบว่าเอกสารมีความถูกต้อง มีการอัปเดต ยืดหยุ่น และนำกลับมาใช้ใหม่ได้
21-25 ตุลาคม 2020: การแก้ไขและลิงก์ ในระยะนี้ ฉันจะตรวจสอบงานของตัวเองเพื่อกำจัดข้อผิดพลาดทางไวยากรณ์และโครงสร้าง รวมถึงตรวจสอบความถูกต้องของงานอีกครั้ง นอกจากนี้ เราจะเพิ่มลิงก์และการอ้างอิงระหว่างส่วนต่างๆ ตาม IA เพื่อให้แน่ใจว่าเอกสารประกอบเป็นไปตามแผนที่ความรู้ที่จัดทำขึ้นก่อนหน้านี้
26 ตุลาคม 2020 - 31 ตุลาคม 2020: เวอร์ชันสุดท้ายสำหรับการส่ง ฉันจะลิงก์ไฟล์มาร์กดาวน์ทั้งหมด สร้างสารบัญ และแชร์ฉบับร่างกับที่ปรึกษา ไฟล์นี้จะใช้เป็นการส่งฉบับร่างแรกในรูปแบบแพ็กเกจที่สมบูรณ์
1 พฤศจิกายน 2020 - 5 พฤศจิกายน 2020: ทบทวนครั้งแรก ในช่วง 5 วันนี้ ฉันจะพูดคุยเรื่องฉบับร่างแรกกับที่ปรึกษา เราจะขอความคิดเห็นจากพวกเขาและพูดคุยเกี่ยวกับไอเดียกับพวกเขาเพื่อสร้างรายการการแก้ไขที่จำเป็น
6-12 พฤศจิกายน 2020: การแก้ไขครั้งแรก เราจะแก้ไขเอกสารฉบับร่างฉบับแรกด้วยความช่วยเหลือจากความคิดเห็นของที่ปรึกษา การแก้ไขจริงจะขึ้นอยู่กับลักษณะของความคิดเห็นและความคิดเห็น แต่วัตถุประสงค์ของการนํามาใช้ซ้ำ ความถูกต้อง และความยืดหยุ่นจะเป็นจุดศูนย์กลางของขั้นตอนการแก้ไข
13 พฤศจิกายน 2020 - 15 พฤศจิกายน 2020: การตรวจสอบครั้งที่ 2 หลังจากการแก้ไขเบื้องต้นเสร็จสิ้น ฉันจะพูดคุยถึงความคืบหน้ากับที่ปรึกษาและทีมที่เกี่ยวข้องอีกครั้ง การพูดคุยเหล่านี้จะมุ่งเน้นที่การแก้ไขในเวอร์ชันแรกและจะไฮไลต์ปัญหาอื่นๆ ที่อาจเกิดขึ้นในกระบวนการแก้ไขด้วย
16-19 พฤศจิกายน 2020: การแก้ไขครั้งที่ 2 จากนั้นเราจะใช้เวลา 4 วันในการแก้ไขเอกสาร เวอร์ชันที่ผลิตขึ้นจากผลลัพธ์นี้จะมีการพูดคุยกับที่ปรึกษาเพื่อปรับให้เป็นรูปเป็นร่างในขั้นสุดท้าย เมื่อสิ้นสุดระยะนี้ เอกสารจะอยู่ในขั้นสุดท้ายและพร้อมที่จะอัปโหลดไปยังเว็บไซต์และที่เก็บ GitHub
20-23 พฤศจิกายน 2020: การอัปโหลดในเว็บไซต์ หลังจากทำการแก้ไขที่จำเป็นทั้งหมดแล้ว ระบบจะอัปโหลดเอกสารไปยังเว็บไซต์ เราจะจัดการกับปัญหาที่เกิดขึ้นในกระบวนการนี้อย่างเหมาะสมเนื่องจากเรายังมีเวลาอีก 2-3 วันในการจัดทำเอกสาร
24-28 พฤศจิกายน 2020: รายงานโปรเจ็กต์ ระบบจะสร้างรายงานโดยละเอียดของโปรเจ็กต์ในช่วง 5 วันนี้ วัตถุประสงค์ ความยากลำบาก ปัญหา และวิธีแก้ปัญหาที่นำเสนอจะเป็นส่วนหนึ่งของรายงานโปรเจ็กต์ โดยจะมีการแชร์รายงานนี้กับที่ปรึกษาเพื่อขอความคิดเห็น
วันที่ 29-30 พฤศจิกายน 2020: การส่งครั้งสุดท้าย ส่งโปรเจ็กต์พร้อมไฟล์ทั้งหมดและรายงานโปรเจ็กต์ให้ที่ปรึกษา การตรวจสอบโปรเจ็กต์ทั้งหมดจะดำเนินการผ่านการประชุม/การสนทนากับที่ปรึกษาและทีมที่เกี่ยวข้อง
ตลอดระยะเวลาของโปรเจ็กต์ เราจะปรึกษาที่ปรึกษาเพื่อรับความคิดเห็นอันมีค่า โดยคุณสามารถเปลี่ยนแปลงเป้าหมายเหล่านี้ทั้งหมดได้ตามที่ได้พูดคุยกับที่ปรึกษาในช่วงการสร้างความสัมพันธ์ในชุมชนและช่วงตรวจสอบข้อเสนอ
เกี่ยวกับฉัน ฉันจบการศึกษาระดับปริญญาตรีสาขาวิศวกรรมไฟฟ้าและระดับบัณฑิตศึกษาสาขาการสื่อสารทางเทคนิคและวิชาชีพจากมหาวิทยาลัย North Carolina State University ฉันมีประสบการณ์ในด้านเทคนิคและการเขียนและแก้ไขแบบมืออาชีพ การสื่อสารและการจัดการเนื้อหา การศึกษาความสามารถในการใช้งานเว็บและอุปกรณ์เคลื่อนที่ และการออกแบบวิธีการ ฉันเคยทำงานเป็นบรรณาธิการผู้ช่วยสำหรับสิ่งพิมพ์ออนไลน์ (Global Village Space) และเป็นนักศึกษาฝึกงานด้านการสื่อสารของ Duke Forge ที่มหาวิทยาลัย Duke นอกจากนี้ ฉันยังสนใจงานเขียนเชิงสร้างสรรค์ด้วย