為專案選好名字

• 盡可能好記，也就是以英文好發音
• 可使用雙關語，如果有能聯想到專案內容的連結的話
• 可以盡量不要重複
• 如果有對應的頂級網域就更好

清楚的使命聲明 ( Mission Statement )

• 如何讓使用者在 30 秒內明白專案內容並引起他們的興趣
• 通常在首頁或是專案名稱正下方
• 應該是具體的、限制性、簡短的描述

聲稱為開源專案

• 很多專案都是在下載才列出來
• 甚至沒有選擇許可證
• 應該在專案敘述中強調這件事情並給出確切許可證
• 也可以另外開啟一個文件版面說明專案版權選擇細節

列出專案功能與需求 ( Features and Requirements List )

• 在快速看過這些專案後，通常訪問對象會有 5 分鐘深入了解細節
• 這時候應該要說明專案支持的功能
• 如果尚未完成他，可以加註 (in progress) 或 (planned)
• 同時要說明運行你的專案需要的開發或運行環境需求

例如：

Features:

  - XXXXX

  - (planned) XXXXX

Requirements:

  - Python a.b or higher

• 看完這些能使讀者快速判斷他是否能使用或參與你的專案

說明開發狀況 ( Development Status )

• 讀者同時也會想知道你對專案的承諾是否有具體實現
• 對於成熟的專案，大家想知道專案的維護模式如何進行、新版本的發行頻率、錯誤報告的修正速度
• 為了要回答這些問題，要有一個提說明開發狀況的頁面
• 並且列出專案的目標以及近期專案開發上需要協助的地方
• 也可以說明歷史版本記錄，以及功能列表
• 不要怕告知專案目前的缺陷，如果讓使用者誤以為沒有缺陷是很糟糕的事情
• 長遠來看保守一些是好事，如果能比讀者認為的穩定得多自然而然會有口碑

提供下載 ( Downloads )

• 對於很多潛在的專案成員來說，安裝失敗是最挫折的事情
• 最好讓發行的機制盡量方便、標準化且低成本
• 最好有標準的安裝流程，並且不要偏離太多
• 提供執行檔可能初期還不太必要，除非有針對特別普通使用者做簡單發行版本
• 要有一個唯一的版本號，這樣使用者才能去比較不同的版本的差異

版本控制與議題追蹤

• 比較熟悉就不記了…

溝通管道

• 很多參與者不一定想投入到專案中，但樂於追蹤最新消息
• 專案早期可能有更高比例的開發人員而非使用者，或是兩者相當模糊
• 如何平衡兩者的溝通管道很重要，並且不會造成大家反感或覺得太多灌水

開發者指南 Developer Guidelines

• 如果有人想參與的專案中，可能會想要有一個開發者指南
• 開發者指南通常不是太技術性，而是單純解釋了開發者如何與用戶互動和完成工作
• 通常包含幾個資訊：
  • 說明能和其他貢獻者溝通交流的平台在哪裡
  • 如果有錯誤要報告或是想提交 Patch 怎麼做
  • 可以參考 OpenOffice.org - Guidelines

撰寫文件

• 剛開始一個專案時，最好限制文件的範圍，否則很難逐步完成
• 一個好的基本文件要包含：
  • 告訴讀者他需要的技術水平，並會學習到什麼
  • 清楚的使用和設置說明，並且告訴使用者如何檢查他正確的設置完成（例如跑個 demo code）
• 給予一個簡單的教程，使得人們不會過早放棄
• 對於尚未完成的文件區塊可以打上未完成標籤，甚至鼓勵大家參與來撰寫
• 不要過分強調專案的缺點，專案剛開始有很多缺點很正常，關鍵時刻做說明即可

維護 FAQ

最基本的溝通工具

• 網站
• 郵件列表 Mailing list
• 議題追蹤 Bug tracking
• 實時討論 Real-time chat

…

有點累了… 剩下我先看完在做筆記吧！

Tags: reading open source

« 〈 Producing Open Source Software 〉閱讀筆記 1 Emacs 中使用 gnus 的基本快捷鍵 »