Standard for Public Code

← 程式碼要有文件 ← 程式碼有文件 ← Document the code Use open standards → 採用開放標準 → 採用開放標準 →

目次

  1. 需求規定
  2. 測試方式
  3. 公共政策制定者:需要的工作
  4. 管理人員:需要的工作
  5. 開發人員與設計師:需要的工作
  6. 延伸閱讀

使用白話的英語

英語是軟體開發領域中的實際 協作語言。

公家機關資訊需要讓所有選民都能取用。簡單且白話的語言,能讓更多人能瞭解程式碼與其功用。

翻譯可以讓更多人有機會認識程式基底。用語越是簡單明暸,製作與維護翻譯的成本就越低。

需求規定

  • 程式基底的所有文件都「必須」使用英語。
  • 所有原始碼都「必須」使用英語編寫,其中政策是由機器 解讀當作程式碼的部分則除外。
  • 任何合捆的政策如果沒有英語版本,則「必須」隨附英語版摘要。
  • 任何翻譯版本皆「必須」跟隨英語版本更新,以維持在最新狀態,反之亦然。
  • 程式基底中「不應該」使用首字母縮字、縮寫、雙關語,或法律/非英語/行業特定詞彙;如果有的話,則需要在這些用語出現之前先行解釋,或是附上解釋該用語的網頁連結。
  • 根據《網頁內容近用性無障礙指引 2》的建議,文件內容「應該」以國中識讀程度為主。
  • 「可選擇」是否提供任何程式碼、文件、測試等的翻譯版。

測試方式

  • 確認程式基底文件有英語版本。
  • 確認原始碼為英語,確認任何非英語內容都是政策,或確認術語在其前方有先行說明等。
  • 確認任何非英語政策都有隨附英語版摘要。
  • 確認翻譯版與英語版內容相同。
  • 確認文件當中,沒有任何未說明的首字母縮寫字、縮寫、雙關語,或法律/非英語/行業特定詞彙等。
  • 檢查文件的拼字、文法與易讀性等。

公共政策制定者:需要的工作

  • 在過程中經常與其他管理人員、開發人員與設計師測試,確認他們是否瞭解您們正要交付的程式碼與其文件的內容。

管理人員:需要的工作

  • 在團隊內部與利害關係人之間的內部溝通中,試著限制首字母縮寫字、縮寫、雙關語,或法律/非英語/行業特定詞彙的使用。如果有使用到的話,則將這些用語加入詞彙表,並且在 使用這些詞彙的地方加上詞彙表連結。
  • 以批判性觀點看待提案與修改當中的文件與描述。如果有您看不懂的內容,很有可能其他人也同樣迷惘。

開發人員與設計師:需要的工作

  • 經常與政策制定者和管理人員測試,確認他們是否瞭解您們正要交付的程式碼與其文件的內容。
  • 詢問身處不同背景情境的人(像是另一個程式基底的開發人員)是否能瞭解內容。

延伸閱讀