一個人的開源專案,文件要寫多少?
你有沒有做完一個小工具,準備公開時,就順手請 AI 幫忙把文件也補齊?現在用 AI 整理使用說明很方便,原本懶得從空白頁寫起的安裝步驟、操作範例,都能先有個草稿。既然都請它寫了,再補一份貢獻指南、行為準則,好像也不費什麼力氣,專案看起來還更完整。
我之前準備公開一套 AI 協作框架時,也整理出了一整套文件。它用 Markdown 和 YAML 這類文字檔,描述不同 AI 角色該做什麼,以及工作要怎麼交接,讓我不用每次重新交代同一套分工。原本想分享的是這個做法,整理到後來,專案裡卻已經有貢獻流程、社群規範和一大份內部架構說明。
只是文件生出來之後,裡面的流程還是得有人照著做、隨著專案更新。當時我仍打算以一人維護的方式經營專案,並沒有要照那套完整制度運作,後來便把其中幾份文件從對外版本移除,保留自己查閱需要的內容。我開始想的是,第一次看到這個專案的人,到底缺哪一份說明;如果他連怎麼開始用都不知道,我先寫完分支命名規則,好像也幫不上忙。
我刪掉的是哪一種文件
GitHub 上的專案通常會有一份 README,直接顯示在專案首頁,讓人知道這是什麼、如何使用。想協助修改的人,則可能需要 CONTRIBUTING,也就是貢獻指南,裡面交代怎麼準備開發環境、檢查修改結果,以及把變更交給維護者。兩份文件的讀者可能是同一個人,卻是在不同時候找答案。
我那次移除的是 CONTRIBUTING、Code of Conduct(行為準則),以及 ARCHITECTURE(內部架構說明)。授權條款和安全回報說明仍然保留,使用者需要的安裝方式也沒有一起拿掉。這是在調整當下對外維護的文件範圍,並不是刪光說明、只留下程式碼。
其中最需要分開看的是架構文件。未來協作者可能需要知道檔案怎麼組合,第一次使用的人卻未必需要讀完每個設計決策。後來我又把安裝、基本概念、自訂方式等使用說明拆進文件目錄,從首頁連過去。內部筆記可以先留給自己,但別人操作時缺的說明,還是得補回公開文件裡。
對我來說,成本主要在寫完之後。測試指令換了,貢獻指南得跟著改;工作方式調整了,審查流程也得更新。AI 可以協助更新內容,但裡面的指令是否真的能跑、承諾的流程是否做得到,仍得自己確認。文件寫得越完整,需要核對的地方也越多。
公開前先交代什麼
讓第一個使用者能開始
我現在會先從使用者的第一個動作往回看。對這套 AI 協作框架來說,他需要知道哪些工具能用、怎麼安裝,再用一個小任務確認角色有正常運作。至於我當初比較過哪些設計、為什麼淘汰某種分工方式,可以放在後面,不必擋在開始使用之前。
換成一般的小工具也一樣。README 至少要說明它解決什麼問題、需要先準備什麼,以及照著做完會看到什麼結果。如果還有尚未支援的平台、可能改動的功能,或只在自己的環境測過,也要讓人事先知道。只寫「安裝後即可使用」,卻沒交代安裝成功長什麼樣子,讀者卡住時還是只能猜。
這些資訊不一定要各自拆成一份檔案。我會先按用途分配,再決定要放在哪裡。
| 讀者現在需要知道的事 | 起步時可以怎麼放 | 什麼時候再擴充 |
|---|---|---|
| 這是什麼、如何開始、有哪些限制 | README,加一個能照做的例子 | 首頁太長時,把安裝與進階用法拆出去並留下連結 |
| 可以如何使用、修改與散布 | 放好適用的授權條款 | 授權需求改變時重新評估,不等有人提問才處理 |
| 一般問題、安全問題要去哪裡回報 | README 留一般入口,安全回報另給非公開管道 | 回報需要的資訊反覆缺漏時,再補範本 |
| 想協助修改,該先做什麼 | 先說是否接受修改,並留下討論想法的入口 | 開始邀請貢獻時,補開發與檢查步驟 |
| 多人一起討論或維護,要遵守什麼 | 準備招募貢獻或經營討論時,先交代行為邊界與處理方式 | 有固定協作者時,再補審查分工與發布權責 |
這張表是我整理一人專案時的取捨,沒有規定 CONTRIBUTING 一定得晚寫。如果現在就需要請別人協助,先用幾行交代怎麼參與,會比讓對方來回問更省事。
安全回報不能等
一般操作問題,可以請使用者建立 GitHub issue;它是專案用來追蹤問題與建議的討論頁。安全漏洞則要有私下回報的方法,不能等第一個人把敏感內容貼到公開留言區,才開始決定該寄到哪裡。我當時保留的 SECURITY 文件,就把一般問題和安全回報分開處理。
GitHub 提供私人漏洞回報功能,但在文件裡寫「請使用私人回報」不等於功能已經開啟。依 Configuring private vulnerability reporting for a repository 的說明,維護者需要啟用功能,對方才會看到回報按鈕;通知設定也會影響維護者能否收到提醒。如果選擇用這個管道,公開前就要確認入口真的可用,而不只是把網址貼上去。
有人想幫忙時怎麼補
假設有人試用後,在 issue 問:「我照著安裝說明做,但不知道設定檔要放哪裡。」這時先回覆位置,再把答案補到 README 對應的步驟旁邊就好。對方卡在使用說明,新增一份貢獻指南並不能幫他完成安裝。
接著,假設他說願意幫忙補一個安裝範例,事情才進到協作。我會先說明範例應放在哪裡、要涵蓋哪種環境,以及送出前怎麼確認步驟可用。不能等他全部做完,才告訴他我其實還要求另一組檢查;如果檢查方式只有我知道,我就得先補出來,或明講哪些部分會由我協助驗證。
對方把修改送成一筆變更提案,請我審查是否合併;GitHub 把這種提案稱為 pull request,簡稱 PR。第一輪合作結束後,可以把剛才那段說明整理進 CONTRIBUTING。內容不用突然長成一套制度,先讓下一位貢獻者知道「動手前先討論範圍、修改放哪裡、完成後如何檢查」就有用。之後發現每次都漏掉相同資訊,再把那一項加進 PR 範本。
若改的是功能,檢查方式可能是執行測試;若改的是安裝說明,就應實際照步驟走過。主要靠 AI 做修改的人,可以先請它列出能重做的檢查步驟,自己跑一次並保留結果,再決定文件要記哪些操作。AI 產出的「所有測試均已通過」,仍要有實際執行結果可以核對,不能直接拿這句話當驗收。
拆出 CONTRIBUTING 也有檔名以外的好處。GitHub 的 Setting guidelines for repository contributors 說明,放在支援位置的貢獻指南,會在建立 issue 或 PR 時提供連結。協作開始固定發生後,把規則放到對方準備送出修改的位置,比一直藏在 README 中段更好找。
我把這種安排理解成「需要時再補規則」。時間點可以是第一次回饋,也可以是自己決定開始找人幫忙;不必硬等到第一個 PR 已經送來,更不用等同一個人踩兩次坑,才承認文件缺了一段。
什麼時候該提早寫
查資料時,我也看到跟我當時選擇不同的建議。Starting an Open Source Project 把授權、README、貢獻指南與行為準則都列為起步文件,也提到早期的貢獻指南可以很簡單。這個建議有道理,清楚的參與方式本來就能降低別人第一次幫忙的門檻,不能只看「現在沒人提修改」,就推論永遠不需要寫。
如果公開的目的就是招募協作者,或已經準備經營討論區,我會在邀請之前補好參與方式與行為準則,包括不當行為要向誰回報、維護者如何處理。人少也可能發生衝突,不能把「等有需要」解讀成等第一次爭執後再想規則。同樣地,多個人開始審查與發布時,誰可以合併、誰可以發版,也應該事先談好。
我的起點比較小,先把自己做的工具分享出去,由自己維護,沒有打算一開始就建立共同決策的社群。在這個前提下,我願意承擔第一次有人想幫忙時,多花一點時間說明和補文件的成本。所以我會先在 README 留下求助入口與是否接受貢獻,其他制度等實際互動再補。
下次整理自己的專案,我會先挑一個已經能用的功能,從 README 開始照著做一次,看看哪一步還得靠腦中的記憶補完。那就是現在該寫的地方。至於暫時用不到的審查層級和完整提案範本,先留下需要時再補的空間,至少不用一邊改功能,一邊通知只有自己一個人的委員會。(當然,最好的習慣還是在製作過程中,就順手把需要的文件補好,省得最後再靠記憶補作業。)