5 ms·

Art of README (2020)

203 points by graderjs 4y ago

andix 4y ago
A good Readme can make mediocre software really good. If it does it’s job, and people understand how and when to use it, this is already a lot.
wizerno 4y ago
This is another resource which carries useful tips along the same lines: https://skerritt.blog/make-popular-open-source-projects/ https://skerritt.blog/make-popular-open-source-projects/
motoboi 4y ago
Perl is very god at that because of perldocs. Javadoc is also great, but it's too much. I miss that very much.
- mindcrime 4y ago
  Perl is very god Typo, Freudian slip, or ???
  - jdthedisciple 4y ago
    ... or autocomplete
  - mmmpop 4y ago
    Perl is right before my time b/c PHP, but the idea that "bless" is a keyword that associates an object with a class seemed like an easter egg of "what exactly was he getting at?"
- jandrese 4y ago
  One of the things Perl got right was insisting that the POD start with a minimal working code example that you can build off of.
5350-uiop-1130 4y ago
> keep your README succinct so why isn't yours.... node community has horrible documentation in general, at least in my experience of some shitty npm packages i was cursed to deal with. giving non executable code samples to start.
- akpa1 4y ago
  > so why isn't yours.... Because this isn't a software project with a README, this is a piece of writing about READMEs that happens to be in a README.md file, likely because that's what GitHub displays by default.
  - AndrewUnmuted 4y ago
    - burnished 4y ago
      It's a means of widely distributing text files that can be commented on, forked, improved, merged, and presents a history. Your alternative is hosting a blog and losing all of those features and free hosting. I do not understand how you can hold your opinion, excepting perhaps an unexamined assumption that all repositories must be exclusively for serious coding projects. Which would be understandable but, I think, in error.
  - forgetfulness 4y ago
    It would serve the purpose better if it were structured closer to its own ideal of a README than a quaint millenial blog post from the 2010s
    - 5350-uiop-1130 4y ago
      the front end community is full of 20 somethings who are rediscovering the wheel every other month.
    - spartanatreyu 4y ago
teddyh 4y ago
Here are the traditional best practices of how README files should look: • https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... • https://www.gnu.org/prep/standards/html_node/Releases.html#index-README-file https://www.gnu.org/prep/standards/html_node/Releases.html#i...
- chrismorgan 4y ago
  > By ancient convention, this is the first file intrepid explorers will read after unpacking the source. > 2. A pointer to the project website (if it has one) And there you see a major shift that has happened in the last fifteen or so years. README files used to be for once you had obtained the code. But then GitHub co-opted them to be the home page, and other forges have by and large followed suit. I get why (repository info blocks on SourceForge and similar weren’t great), but I wish that brand of pragmatism hadn’t happened. Fortunately, I think that if you create another readme file in a .github/ subdirectory, GitHub should use that rather than the top-level readme file, so if you want to leave a proper readme file at the top level but direct casual viewers to an actual separate website with a deliberately stub GitHub readme file (“Go to <https://example.com https://example.com> for information about the product, or look at the [in-repository README.md file](../README.md) for information about the code.”), you should be able to do so. Otherwise you’re stuck either stuffing far too much inappropriate stuff into the readme file, or having people miss out on what they should see. If I were in this situation, I’d probably do that. (See also https://news.ycombinator.com/item?id=32211789 https://news.ycombinator.com/item?id=32211789 where I made this observation 11 days ago when a link to a code repository that contained a traditional README, instead of to a project page, led to surprise.)
  - pussycat 4y ago
    Interesting how in `cgit` you can auto detect README files, but the default page for a repository isn't the readme, it's the commit summary history. I'd say it's more "traditional".
    - 4y ago
masukomi 4y ago
I feel like posting Matt Parker's spectacular "Readme Driven Development" lightning talk is obligatory here: https://youtu.be/23xzRCoDZf4 https://youtu.be/23xzRCoDZf4
thenerdhead 4y ago
READMEs are necessary. They are like instructions that come with appliances. Most of us will try to just use or assemble the thing without instructions and then sure enough we dig through the trash or try to find another manual online to humble us. I think some READMEs can go a bit over the top with every affordance or badge you can muster however. But I think we'd rather have something than nothing which is all too common in software.
zfxfr 4y ago
And before the README.MD there was the good old FILE_ID.DIZ
- stevekemp 4y ago
  I remember READ.ME, and README.1ST, both being common. But seeing FILE_ID.DIZ takes me back a few decades!
dietrichepp 4y ago
README is always the first commit. What is this project? What are its goals? This seems obvious to me now but it was not obvious when I was younger. I will forget what a project is.
- Shish2k 4y ago
  > I will forget what a project is. I sometimes completely forget what a project is, but I nearly _always_ forget how to build / run / test / deploy it… Now I make sure that simple copy-pastable one-liners for those four steps are included pretty much right after I’ve written my top-level “what is this for” sentence.
  - Zopieux 4y ago
    This so much. I can pretty easily reverse engineer why me, or some folk on the internet, wrote some code. It might take time, but reading a few files should do it. The 'effing building or running process and its unwritten dependencies/twirks though? Hell, better rewrite the project from scratch than having to figure out the obscure incantations I used 6 month ago. I'm so glad our industry heavily pivoted towards package managers with consistent `$ pkgmanager build` processes. I've lost count of the number of times I did not document my Python dependencies when I was younger.
  - graderjs 4y ago
    Me too, there's so much accrued knowledge and hard won time recorded for me in my bash install files of my projects
Torwald 4y ago
README.TXT ist not all uppercase because of anything Unix, but because VAX/VMS had six dot three chars long file names and all of them upper case.
- eesmith 4y ago
  https://en.wikipedia.org/wiki/README https://en.wikipedia.org/wiki/README points out that "README.TXT" was used in 1974 at http://pdp-10.trailing-edge.com/decus_20tap3_198111/01/decus/20-0079/readme.txt.html http://pdp-10.trailing-edge.com/decus_20tap3_198111/01/decus..., which predates VAX/VMS by a couple of years. That was for a DECsystem-10, so still DEC, just a bit earlier.
sinoue 4y ago
As a former product manager the readme was used as a confessional for known bugs that were deferred and that users might run into, but had work arounds or didn't happen consistently.
- sitzkrieg 4y ago
  i miss this usage. way more useful than developer centric stuff that is shown at a code repo.. im at already at the code, maybe a contributing or development file, or anything else really
  - paulryanrogers 4y ago
    Especially USAGE with a few common examples, yet not a huge tome.
norwalkbear 4y ago
Gitlab has a good starter readme example
sesm 4y ago
In the early days of Clojure, community libraries used to have the best readme-s I’ve ever seen. They always wrote what problem this library is trying to solve, what other solutions exist and how this solution compares to the others. Sadly, this tradition slowly faded away, some readme-s of todays Clojure libraries are indistinguishable from typical JS noob-trap frameworks.
- keule 4y ago
  You reminded me of the HikariCP library and it’s documentation: Clear and simple with references to other libraries trying to accomplish the same thing. It is not in the clojure space though. https://github.com/brettwooldridge/HikariCP https://github.com/brettwooldridge/HikariCP
thirdmunky 4y ago
The section on caring about people's time [0], a.k.a. prefix-competitive docs, is great. Prefix-competitiveness is widely and easily applicable and provides a lot of juice despite how obvious it sounds. It's relevant for docs, slideshows, emails, and communication in general. (I wish that section came first.. :p) [0] https://github.com/hackergrrl/art-of-readme#care-about-peoples-time https://github.com/hackergrrl/art-of-readme#care-about-peopl...
emacs28 4y ago
> Do you have a CI badge to show build/test status? This signal would better reach important parties by emailing maintainers or automatically creating an issue. I find a CI and coverage badge worthwhile because they provide a quick reassurance that the project at least has some form of test plan, which immediately distinguishes it from many other repos.
FounderBurr 4y ago
A readme file should have some cool ansi art, shout outs and serials if needed. Anything more is just wanking.

203 points by graderjs 4y ago

A good Readme can make mediocre software really good. If it does it’s job, and people understand how and when to use it, this is already a lot.

wizerno 4y ago

This is another resource which carries useful tips along the same lines: https://skerritt.blog/make-popular-open-source-projects/ https://skerritt.blog/make-popular-open-source-projects/

motoboi 4y ago

Perl is very god at that because of perldocs. Javadoc is also great, but it's too much. I miss that very much.

mindcrime 4y ago
Perl is very god Typo, Freudian slip, or ???
- jdthedisciple 4y ago
  ... or autocomplete
- mmmpop 4y ago
  Perl is right before my time b/c PHP, but the idea that "bless" is a keyword that associates an object with a class seemed like an easter egg of "what exactly was he getting at?"
jandrese 4y ago
One of the things Perl got right was insisting that the POD start with a minimal working code example that you can build off of.

5350-uiop-1130 4y ago

> keep your README succinct so why isn't yours.... node community has horrible documentation in general, at least in my experience of some shitty npm packages i was cursed to deal with. giving non executable code samples to start.

akpa1 4y ago
> so why isn't yours.... Because this isn't a software project with a README, this is a piece of writing about READMEs that happens to be in a README.md file, likely because that's what GitHub displays by default.
- AndrewUnmuted 4y ago
  - burnished 4y ago
    It's a means of widely distributing text files that can be commented on, forked, improved, merged, and presents a history. Your alternative is hosting a blog and losing all of those features and free hosting. I do not understand how you can hold your opinion, excepting perhaps an unexamined assumption that all repositories must be exclusively for serious coding projects. Which would be understandable but, I think, in error.
- forgetfulness 4y ago
  It would serve the purpose better if it were structured closer to its own ideal of a README than a quaint millenial blog post from the 2010s
  - 5350-uiop-1130 4y ago
    the front end community is full of 20 somethings who are rediscovering the wheel every other month.
  - spartanatreyu 4y ago

teddyh 4y ago

Here are the traditional best practices of how README files should look: • https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... • https://www.gnu.org/prep/standards/html_node/Releases.html#index-README-file https://www.gnu.org/prep/standards/html_node/Releases.html#i...

chrismorgan 4y ago
> By ancient convention, this is the first file intrepid explorers will read after unpacking the source. > 2. A pointer to the project website (if it has one) And there you see a major shift that has happened in the last fifteen or so years. README files used to be for once you had obtained the code. But then GitHub co-opted them to be the home page, and other forges have by and large followed suit. I get why (repository info blocks on SourceForge and similar weren’t great), but I wish that brand of pragmatism hadn’t happened. Fortunately, I think that if you create another readme file in a .github/ subdirectory, GitHub should use that rather than the top-level readme file, so if you want to leave a proper readme file at the top level but direct casual viewers to an actual separate website with a deliberately stub GitHub readme file (“Go to <https://example.com https://example.com> for information about the product, or look at the [in-repository README.md file](../README.md) for information about the code.”), you should be able to do so. Otherwise you’re stuck either stuffing far too much inappropriate stuff into the readme file, or having people miss out on what they should see. If I were in this situation, I’d probably do that. (See also https://news.ycombinator.com/item?id=32211789 https://news.ycombinator.com/item?id=32211789 where I made this observation 11 days ago when a link to a code repository that contained a traditional README, instead of to a project page, led to surprise.)
- pussycat 4y ago
  Interesting how in `cgit` you can auto detect README files, but the default page for a repository isn't the readme, it's the commit summary history. I'd say it's more "traditional".
  - 4y ago

masukomi 4y ago

I feel like posting Matt Parker's spectacular "Readme Driven Development" lightning talk is obligatory here: https://youtu.be/23xzRCoDZf4 https://youtu.be/23xzRCoDZf4

thenerdhead 4y ago

READMEs are necessary. They are like instructions that come with appliances. Most of us will try to just use or assemble the thing without instructions and then sure enough we dig through the trash or try to find another manual online to humble us. I think some READMEs can go a bit over the top with every affordance or badge you can muster however. But I think we'd rather have something than nothing which is all too common in software.

zfxfr 4y ago

And before the README.MD there was the good old FILE_ID.DIZ

stevekemp 4y ago
I remember READ.ME, and README.1ST, both being common. But seeing FILE_ID.DIZ takes me back a few decades!

dietrichepp 4y ago

README is always the first commit. What is this project? What are its goals? This seems obvious to me now but it was not obvious when I was younger. I will forget what a project is.

Shish2k 4y ago
> I will forget what a project is. I sometimes completely forget what a project is, but I nearly _always_ forget how to build / run / test / deploy it… Now I make sure that simple copy-pastable one-liners for those four steps are included pretty much right after I’ve written my top-level “what is this for” sentence.
- Zopieux 4y ago
  This so much. I can pretty easily reverse engineer why me, or some folk on the internet, wrote some code. It might take time, but reading a few files should do it. The 'effing building or running process and its unwritten dependencies/twirks though? Hell, better rewrite the project from scratch than having to figure out the obscure incantations I used 6 month ago. I'm so glad our industry heavily pivoted towards package managers with consistent `$ pkgmanager build` processes. I've lost count of the number of times I did not document my Python dependencies when I was younger.
- graderjs 4y ago
  Me too, there's so much accrued knowledge and hard won time recorded for me in my bash install files of my projects

Torwald 4y ago

README.TXT ist not all uppercase because of anything Unix, but because VAX/VMS had six dot three chars long file names and all of them upper case.

eesmith 4y ago
https://en.wikipedia.org/wiki/README https://en.wikipedia.org/wiki/README points out that "README.TXT" was used in 1974 at http://pdp-10.trailing-edge.com/decus_20tap3_198111/01/decus/20-0079/readme.txt.html http://pdp-10.trailing-edge.com/decus_20tap3_198111/01/decus..., which predates VAX/VMS by a couple of years. That was for a DECsystem-10, so still DEC, just a bit earlier.

sinoue 4y ago

As a former product manager the readme was used as a confessional for known bugs that were deferred and that users might run into, but had work arounds or didn't happen consistently.

sitzkrieg 4y ago
i miss this usage. way more useful than developer centric stuff that is shown at a code repo.. im at already at the code, maybe a contributing or development file, or anything else really
- paulryanrogers 4y ago
  Especially USAGE with a few common examples, yet not a huge tome.

norwalkbear 4y ago

Gitlab has a good starter readme example

sesm 4y ago

In the early days of Clojure, community libraries used to have the best readme-s I’ve ever seen. They always wrote what problem this library is trying to solve, what other solutions exist and how this solution compares to the others. Sadly, this tradition slowly faded away, some readme-s of todays Clojure libraries are indistinguishable from typical JS noob-trap frameworks.

keule 4y ago
You reminded me of the HikariCP library and it’s documentation: Clear and simple with references to other libraries trying to accomplish the same thing. It is not in the clojure space though. https://github.com/brettwooldridge/HikariCP https://github.com/brettwooldridge/HikariCP

thirdmunky 4y ago

The section on caring about people's time [0], a.k.a. prefix-competitive docs, is great. Prefix-competitiveness is widely and easily applicable and provides a lot of juice despite how obvious it sounds. It's relevant for docs, slideshows, emails, and communication in general. (I wish that section came first.. :p) [0] https://github.com/hackergrrl/art-of-readme#care-about-peoples-time https://github.com/hackergrrl/art-of-readme#care-about-peopl...

emacs28 4y ago

> Do you have a CI badge to show build/test status? This signal would better reach important parties by emailing maintainers or automatically creating an issue. I find a CI and coverage badge worthwhile because they provide a quick reassurance that the project at least has some form of test plan, which immediately distinguishes it from many other repos.

FounderBurr 4y ago

A readme file should have some cool ansi art, shout outs and serials if needed. Anything more is just wanking.