本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- ESLint
- 技術撰稿人：
- Khawar
- 專案名稱：
- 重新整理/重新編寫設定說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要
這項專案的目標是重新建構 ESLint 設定說明文件，並建立有效的資訊架構。這麼做可讓使用者更輕鬆地瀏覽說明文件，並提升說明文件的可用性和實用性。
專案摘要 目前狀態的 ESLint (https://eslint.org/docs/user-guide/configuring) 設定說明文件提供了大量資訊，雖然頁面上有標題、副標題和適當的段落，但說明文件仍可能令人眼花撩亂。我們無法瀏覽特定部分，讓使用者感到不悅。由於缺乏組織，資訊也可能會遺失，無法發揮作用，並要求使用者額外付出努力。
不過，只要完成一系列謹慎步驟，就能解決這些問題。在此重整過程中，我首先建議進行內容稽核。內容稽核不僅有助於找出資訊呈現的問題，還能突顯內容本身的缺點 (例如資訊過時或不完整)。然後，我計劃建立資訊架構 (IA) 來公開知識網路。這樣一來，我們就能根據各種主題將資訊分組，並找出各種密切相關主題之間的連結。透過這兩種做法獲得的洞察資料，將用於將單頁說明文件分成多個頁面。這樣一來，整個套件就能在 Markdown 中連結及交叉參照。因此，我們將推出更有條理的設定說明文件，方便您瀏覽及瞭解相關內容。
動機 雖然我使用開放原始碼軟體已有一段時間，但我對這個詞的瞭解還算新，就像我對 Linting 軟體的瞭解一樣。當我開始透過 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) 完成內容稽核後，我會建立設定文件的資訊架構。我會以易於理解的方式呈現知識網路。這有助於改善資訊流程。
2020 年 9 月 26 日至 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 日至 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 擔任副編輯，也曾在杜克大學的 Duke Forge 擔任通訊實習生。除了這個主題，我也對創作文學感興趣。