Art of README (2020) | Hacker News Reader

Art of README (2020)

github.com

203 pointsgraderjs37 comments

Open articleView on HN

Here are the traditional best practices of how README files should look:

• https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...

• https://www.gnu.org/prep/standards/html_node/Releases.html#i...

> 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> 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 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.)

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".

Presumably because “cgit” is used by the developers of the code and not by the users of the code.

I think it’s clearer to say: the sorts of people that use things like cgit are more likely to be using it just for the repository, and not as the project home page. Certainly that’s how I’m starting to use currently gitweb.

> 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.

> 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.

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

The post gives plenty of examples of the README files it's describing.

the front end community is full of 20 somethings who are rediscovering the wheel every other month.

I feel like posting Matt Parker's spectacular "Readme Driven Development" lightning talk is obligatory here:

https://youtu.be/23xzRCoDZf4

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.

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

Especially USAGE with a few common examples, yet not a huge tome.

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.

> 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.

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.

Me too, there's so much accrued knowledge and hard won time recorded for me in my bash install files of my projects

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

I remember READ.ME, and README.1ST, both being common.

But seeing FILE_ID.DIZ takes me back a few decades!

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

Perl is very god at that because of perldocs.

Javadoc is also great, but it's too much.

I miss that very much.

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.

Perl is very god

Typo, Freudian slip, or ???

... or autocomplete

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-peopl...

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.

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.

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.

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

> 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.

A readme file should have some cool ansi art, shout outs and serials if needed.

Anything more is just wanking.

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.

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..., which predates VAX/VMS by a couple of years.

That was for a DECsystem-10, so still DEC, just a bit earlier.

Gitlab has a good starter readme example

Reply on news.ycombinator.com