本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- ESLint
- 技術文件撰寫者：
- 哈瓦文
- 專案名稱：
- 重新整理/重新編寫設定說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要
本專案的目標是重組 ESLint 的設定文件，並建立有效的資訊架構。這樣可簡化瀏覽作業，同時提升說明文件的可用性和實用性。
專案摘要 目前狀態的 ESLint (https://eslint.org/docs/user-guide/configuring) 設定說明文件會在單一頁面上提供大量資訊。即使網頁上出現標題、子標題和適當的段落，說明文件仍可能令人眼花撩亂。使用者瀏覽頁面中的特定部分無法瀏覽，導致對特定部分有興趣感到不悅。資訊可能會因缺乏組織，而遺失、無法達到目的，以及要求使用者花費更多心力。
不過，這些問題可透過一系列謹慎步驟解決。我提議進行內容稽核是這次重組的第一步，內容稽核不只能協助找出資訊呈現中的問題，還能醒目顯示內容本身簡短的片段 (例如資訊過舊或不完整)。然後我打算打造資訊架構 (IA) 來公開知識網路。這有助於我們依據多個主題彙整資訊，並找出多個密切相關主題之間的連結。透過這兩種做法取得的見解，將使用從單頁說明文件劃分為多頁的文件。接著，您可以在 Markdown 中連結及交叉參照整個套裝方案。因此，設定說明文件更井然有序，更容易瀏覽和理解。
動機 儘管我已有很長時間使用開放原始碼軟體，但對這個詞的瞭解相當新，與我對 Lint 軟體的瞭解相似。開始透過 edX 學習 Python 時，當時我想知道小小錯誤如何影響整個程式碼。我以為會這樣很好地測試您的程式碼，以某些方式找出錯誤，然後說明「linting」一詞。我還沒實際用到程式碼檢查軟體，但相信這些程式碼日後能讓我的生活更輕鬆。
具備電機工程背景和程式設計經驗，我可以更好地瞭解程式設計和程式設計人員的要求。此外，我的技術和專業通訊學士學位讓我成為使用者的倡議者，希望能讓人們的生活更加輕鬆。我的技能和專業知識足以參與這項專案，提升 ESLint 說明文件的價值。
目標 這項專案的首要目標是確保 ESLint 設定頁面的說明文件易於理解，且不會讓使用者感到疲乏。專案成功的關鍵在於，應簡單、完全不使用任何小工具，這樣才能輕鬆瀏覽內容。專案的重要目標如下。- 執行全方位的內容稽核 - 建立資訊架構以瞭解資訊流程 - 改善資訊架構以重新整理說明文件 - 找出內容不同部分之間的連結和參考 - 視需要重新編寫/編輯說明文件部分，以符合重新設定需求
- 確保內容彈性良好且可重複使用
ESLint 的專案說明設定是重要功能，可讓您讓 ESLint 自訂設定。對設定感興趣的使用者大多在特定時間會感興趣一到兩個層面。因此，請務必讓使用者依據自身的興趣選擇他們感興趣的主題，以便有效率地提供解決方案。ESLint 目前的設定說明文件狀態包含大量實用資訊，但內容編排方式有利於使用者感到不堪負荷、不悅並遺失。舉例來說，如果使用者有興趣瞭解 ESLint 中的第三方外掛程式的使用方式，就必須向下捲動畫面，討論如何指定剖析器、環境和全域。整個做法對使用者來說都是備受關注的對象，讓他們離開網站。 同樣地，如果使用者位於網頁的中間位置，想要前往特定版面或只查看類似主題，這就不算容易完成，因為沒有向使用者提供這類輔助資訊。這些問題需要立即關注，因為任何說明文件的品質都取決於其實用性。我在後續的討論中提出瞭解決方案和其他相關問題的解決方案。
內容稽核 重新編排設定說明文件的第一步，就是執行全面的內容稽核。這項稽核旨在找出幾項重大問題，例如過時的內容、重複內容、遺漏的內容等。系統會將你建立的內容稽核試算表提供給管理團隊和說明文件團隊，請對方提供意見回饋。這麼做有助於擬定新策略架構及呈現說明文件。
建立資訊架構，如要瞭解知識網路或設定文件中的資訊流程，建立資訊架構 (IA) 可能很有幫助。內容稽核結果是瞭解和發展資訊流通的理想基礎。系統會建立改良的 IA 版本，以更有效率的方式整理及呈現說明文件。改善 IA 不僅會重組現有內容，還能在文件的各個章節之間找出連結和分支，進而建立高效網路。舉例來說，「設定規則」內容後面可指向「停用含有內嵌註解的規則」的連結。此外，系統也能找出其他這類連結，藉此建立說明文件不同部分之間的關係。
目錄 內容稽核和 IA 會提供適當資訊，以便建立詳細的目錄，並提供可導向說明文件特定章節和子章節的連結。為每個章節分別建立檔案，並將適當的參照新增至其他部分，可為整組文件增添價值。您可以為前往設定說明文件的使用者建立目錄，協助他們在網站上提供所需的資訊。目錄可納入所有第一層和第二層的標題，確保內容簡短扼要。舉例來說，Prettier (https://prettier.io/docs/en/index.html) 就是用來整理說明文件的其中一種方式。
所有說明文件都會使用 Markdown 建立，確保一切井然有序。我們會特別留意，確保相關文件在日後發展或有所變動時可重複使用。
使用工具 有些重要工具可以在製作專案時派上用場 - Draw.io 視需要為 IA 製作插圖 - Atom (或類似的編輯器) 在 Markdown 中撰寫和編輯文件
- GitHub 可確保說明文件的版本管控
里程碑 從提交提案到完成專案，下列重要里程碑可確保專案準時完成，確保流程中的流程安全無虞。
2020 年 7 月 10 日至 2020 年 8 月 16 日：提案審核和選項 我會閱讀 ESLint 的說明文件，並開發完成專案所需的技能 (例如 Markdown 編寫、在 GitHub 上協作)。我也會透過 GitHub 對說明文件做出貢獻，並與其他使用者交流，進一步瞭解說明文件。
2020 年 8 月 17 日至 2020 年 9 月 13 日：社群凝聚期間 我將根據導師和相關團隊的討論內容來修正我的提案。如有需要，我也會編輯目標和里程碑。此外，我會記得列出之後要用來進行專案的工具。
2020 年 9 月 14 日至 2020 年 9 月 19 日：內容稽核 首先是針對專案進行全面稽核，目標是突顯內容和呈現方式的問題。
2020 年 9 月 20 日至 2020 年 9 月 25 日：資訊架構 (IA) 內容稽核完畢後，我會建立設定說明文件的 IA。我會著重於以清楚易懂的方式呈現知識網路內容。這將有助於改善資訊流通。
2020 年 9 月 26 日至 2020 年 9 月 30 日：連結和參考資料會在這個階段分析 IA，並指出說明文件各部分之間的連結和參考資料。我也會為所有部分建立階層，藉此改善應用程式內廣告效益。
2020 年 10 月 1 日至 2020 年 10 月 3 日：最後一張圖。在內容稽核和 IA 取得的深入分析資料的協助下，我接下來要製作一份最終地圖，並納入重新編排的設定說明文件中。這份完善的地圖包含目錄、主題階層，以及說明文件各節間的連結與交叉參照清單。
2020 年 10 月 4 日至 2020 年 10 月 5 日：討論 目前，在編輯說明文件前，我會向導師和相關團隊展示我的研究成果和計畫。他們的意見將有助於調整計畫，並在必要時做出修改。
2020 年 10 月 6 日至 2020 年 10 月 20 日：重新撰寫與編輯 在此期間，針對需要編輯的文件，我會編輯及更新相關的文件區段。系統可能會重新撰寫設定說明文件的某些部分，或是加入新內容。這個階段的重點在於確保說明文件正確無誤、符合現況、具有彈性，且可重複使用。
2020 年 10 月 21 日至 2020 年 10 月 25 日：修正和連結 在這個階段中，我將檢查自己的工作來排除文法和結構錯誤，並再次檢查工作內容是否正確。我也會根據 IA 的規定，在各區段之間加入連結和參考資料，確保文件內容遵循先前開發的知識圖譜。
2020 年 10 月 26 日至 2020 年 10 月 31 日：提交最終版本 我會連結所有 Markdown 檔案、建立目錄，並與導師分享草稿。這會是提交第一份草稿時，採用完整的套裝內容格式。
2020 年 11 月 1 日至 2020 年 11 月 5 日：第一篇評論 在這五天內，我會和導師討論第一份草稿。我會收到他們的意見回饋，並與他們討論我的想法，以便建立一份需要編輯的清單。
2020 年 11 月 6 日至 2020 年 11 月 12 日：首次編輯：在導師的意見回饋的協助下，我將編輯說明文件的第一個草稿。實際的編輯內容取決於註解和意見回饋的性質，但重複使用、準確性和靈活性的目標則是編輯階段的優先因素。
2020 年 11 月 13 日至 2020 年 11 月 15 日：第二次審查 初步編輯完成後，我會再與導師及相關團隊討論進度。這些討論會著重於第一個版本的編輯內容，也會醒目顯示編輯過程中發生的任何其他問題。
2020 年 11 月 16 日至 2020 年 11 月 19 日：第二次編輯：接著，我會預留四天的時間編輯文件。最終產生的版本將與導師討論，歸納出最終版本。在這個階段結束時，文件處於最終形狀，即可上傳至網站和 GitHub 存放區。
2020 年 11 月 20 日至 2020 年 11 月 23 日：在網站上上傳 完成所有必要修改後，系統就會將文件上傳到網站。由於我們仍有幾天的時間著手撰寫文件，因此若處理過程中發生的任何問題，我們將據此進行處理。
2020 年 11 月 24 日至 2020 年 11 月 28 日：專案報告 我們會在這五天內建立專案的詳細報告。目標、問題、問題和解決方案等內容將構成專案報告的一部分。我們會將檢舉內容提供給導師，並告知導師。
2020 年 11 月 29 日至 2020 年 11 月 30 日：最終提交 專案及所有檔案，並將專案報告提交給導師。必須和導師及相關團隊召開會議/討論整個專案。
在專案進行期間，我會持續諮詢導師，取得他們的寶貴意見。這些里程碑都能根據社群凝聚和提案審核期中導師的討論而調整。
關於我 我擁有北卡羅來納州立大學的電機工程學士學位，以及北卡羅來納州立大學的技術與專業溝通學位。我擁有技術與專業的書寫及編輯、溝通與內容管理、網頁和行動裝置可用性研究，以及教學設計方面的經驗。我在杜克大學 (Global Village Space) 擔任線上出版物的副編輯，也是杜克福吉的通訊實習生。並考慮創意寫作，