[HN Gopher] Art of README (2020)
___________________________________________________________________
Art of README (2020)
Author : graderjs
Score : 158 points
Date : 2022-08-04 14:33 UTC (8 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| sinoue wrote:
| 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 wrote:
| 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
| Torwald wrote:
| 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 wrote:
| 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.
| dietrichepp wrote:
| 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 wrote:
| > 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 wrote:
| 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.
| sesm wrote:
| 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.
| zfxfr wrote:
| And before the README.MD there was the good old FILE_ID.DIZ
| mouzogu wrote:
| > 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 wrote:
| > 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.
| forgetfulness wrote:
| 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
| mouzogu wrote:
| the front end community is full of 20 somethings who are
| rediscovering the wheel every other month.
| AndrewUnmuted wrote:
| burnished wrote:
| 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.
| [deleted]
| teddyh wrote:
| 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...
| chrismorgan wrote:
| > _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.)
| pussycat wrote:
| 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".
| teddyh wrote:
| Presumably because "cgit" is used by the developers of the
| code and not by the users of the code.
| chrismorgan wrote:
| 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.
| masukomi wrote:
| I feel like posting Matt Parker's spectacular "Readme Driven
| Development" lightning talk is obligatory here:
|
| https://youtu.be/23xzRCoDZf4
| andix wrote:
| 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 wrote:
| This is another resource which carries useful tips along the same
| lines: https://skerritt.blog/make-popular-open-source-projects/
| thenerdhead wrote:
| 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.
| motoboi wrote:
| Perl is very god at that because of perldocs.
|
| Javadoc is also great, but it's too much.
|
| I miss that very much.
| jandrese wrote:
| 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.
| mindcrime wrote:
| _Perl is very god_
|
| Typo, Freudian slip, or ???
| jdthedisciple wrote:
| ... or autocomplete
| norwalkbear wrote:
| Gitlab has a good starter readme example
___________________________________________________________________
(page generated 2022-08-04 23:00 UTC)