Skip to content
Allen Shaing

2023-02-03 ART OF README

2 min read

Photo by Lanju Fotografie on Unsplash Day 34 明日補班，稍微安排一小時的Study Club給Team做點工作外的補充。

這次我們一起學習怎樣寫出高品質的README以及核心的元素有哪些。 我參考了這個Repo.同時也感謝中文化的作者：

https://github.com/hackergrrl/art-of-readme 不過比較可惜的是在2022年八月就關起來了，目前為RO狀態。 但整體內容根據我過去的相關研讀也都不謀而合，因此作為此次的教材，外加也有繁中版本，雖然平時也都閱讀大量英文檔案，但既然有繁中更可以加速效率。 這邊放幾個有趣的點：

  • README大寫，在系統排序上，可以優於SRC。因爲在ASCII內”A“大於”a“。

The pattern of README appearing in all-caps is a consistent facet throughout history. In addition to the visual strikingness of using all-caps, UNIX systems would sort capitals before lower case letters, conveniently putting the README before the rest of the directory’s content 2

  • 我也常跟團隊說，今天不寫文件，明天就要準備忘記了。

Once 6 months pass, a module without documentation begins to look new and unfamiliar.

  • 這段話我很有感觸，就很像凡事我都會先去理解為什麼會開始。

It is said that those who do not study their history are doomed to make its mistakes again.

  • 在README中我也常提醒團隊要放上cmd完成後的狀態示意圖。

Include the example code in Usage as a file in your repo — maybe as plain text example.js OK，最後附上我的筆記連結於Heptabase。 Peace. By Allen Shaing on February 3, 2023. Canonical link Exported from Medium on March 15, 2023.