> 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".
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.
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.
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'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.
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
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.
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?"
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.
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.
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.
> 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.
• https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...
• https://www.gnu.org/prep/standards/html_node/Releases.html#i...