I'd like to review your README • Hacker News Board

Re: I'd like to review your README

#41

Post by Y-bar » Sat, Apr 17, 2021, 11:41 AM UTC

DandyDev wrote: post #12

sfvisser wrote: post #5

Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place. Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.

To be fair, I think we're talking about READMEs for technical projects here, probably hosted on Github/Gitlab/... And in that context your example is totally clear to me: it's a framework for running (background) jobs asynchronously (i.e. code that does not need to run on the main thread of your program and block) and you can use it both on the server and the browser (so probably JS/TS) and it's not intended to be fe…

I'm not the person you responded to, but I think their peeve stands correct for technical README's as well. I've decided more than once to not continue reading those when is is not clear to me to move on to what might be a similar implementation just because the README never really explained if it was what I was looking for.

The times when I need to read the repo README is when I am not familiar with what I am looking for. I say err on the side on more documentation, err on the side of a better explanation.

Re: I'd like to review your README

#42

Post by purplecats » Sat, Apr 17, 2021, 11:42 AM UTC

kstenerud wrote: post #40

I'd be curious to know how many takers he gets in the first day after being featured on HN!

The population size of HN seems much smaller than I originally had imagined.

Re: I'd like to review your README

#43

Post by kstenerud » Sat, Apr 17, 2021, 11:44 AM UTC

noxer wrote: post #34

I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated Maybe not include any code is the better solution, instead add an example folder.

One thing golang did right is the go playground. When I put code in my README, I also include a playground link.

Example: https://github.com/kstenerud/go-concise-encoding#library-usa...

Re: I'd like to review your README

#44

Post by remoquete » Sat, Apr 17, 2021, 11:52 AM UTC

tirrex wrote: post #11

It would be great if author points us a few READMEs he likes. So, people can avoid many issues before asking for review.

This. Or, you know, some sample pull requests he created.

Re: I'd like to review your README

#45

Post by frou_dh » Sat, Apr 17, 2021, 12:06 PM UTC

sfvisser wrote: post #5

Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place. Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.

Here's my README pet peeve: When the examples for some tool that operates on source code show it operating on its own code.

As a reader unfamiliar with a project, it's unpleasant to have to contend with "meta" at a time when one doesn't even have a solid first-order understanding of the project.

Re: I'd like to review your README

#46

Post by Gadiguibou » Sat, Apr 17, 2021, 12:09 PM UTC

noxer wrote: post #34

I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated Maybe not include any code is the better solution, instead add an example folder.

That's included in Rust![1]

Code examples from the documentation automatically become "documentation tests" to make sure your examples are still up to date when updating your code.

[1] https://doc.rust-lang.org/rustdoc/documentation-tests.html

Re: I'd like to review your README

#47

Post by cdubzzz » Sat, Apr 17, 2021, 12:11 PM UTC

I really appreciate folks who commit time to open source projects for things other than code (e.g. things that may be otherwise neglected).

There was a user on GitHub back in 2019[0] who went around and created logos for a bunch of projects (including one I was working on actively at the time). Out of curiosity I looked the account up recently while working on a new project but it's not longer active.

Translations are another great example of this. That same project that got the logo has also been translated by various people in to eight different languages!

Other ways I'd love to find people devoting time to smaller projects -- accessibility and UX audits. It's hard to account for all this stuff on smaller projects with only one or two primary developers.

[0] https://github.com/reallinfo?tab=overview&from=2019-12-01&to...

Re: I'd like to review your README

#48

Post by nooyurrsdey » Sat, Apr 17, 2021, 12:23 PM UTC

frou_dh wrote: post #45

sfvisser wrote: post #5

Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place. Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.

Here's my README pet peeve: When the examples for some tool that operates on source code show it operating on its own code. As a reader unfamiliar with a project, it's unpleasant to have to contend with "meta" at a time when one doesn't even have a solid first-order understanding of the project.

prism.js the code syntax highlighter is notoriously bad at this.

At first I felt bad for being confused by something so simple. But all their code examples for highlighting refer to their own code and you're right, at the exact moment you're trying to absorb new information it is infuriating to deal with the "meta" examples.

I don't use them out of that alone.

Re: I'd like to review your README

#49

Post by nooyurrsdey » Sat, Apr 17, 2021, 12:24 PM UTC

DandyDev wrote: post #12

sfvisser wrote: post #5

Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place. Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.

To be fair, I think we're talking about READMEs for technical projects here, probably hosted on Github/Gitlab/... And in that context your example is totally clear to me: it's a framework for running (background) jobs asynchronously (i.e. code that does not need to run on the main thread of your program and block) and you can use it both on the server and the browser (so probably JS/TS) and it's not intended to be fe…

Sure the individual words make sense but there's a cognitive load of deciphering that when you're first trying to learn something.

A "plain english" no nonsense definition goes a long way to introduce your concept. Save the fancy technical jargon for further down in the README if you must.

Re: I'd like to review your README

#50

Post by slhck » Sat, Apr 17, 2021, 12:34 PM UTC

nooyurrsdey wrote: post #48

frou_dh wrote: post #45

Earlier quoted context omitted.

Here's my README pet peeve: When the examples for some tool that operates on source code show it operating on its own code. As a reader unfamiliar with a project, it's unpleasant to have to contend with "meta" at a time when one doesn't even have a solid first-order understanding of the project.

prism.js the code syntax highlighter is notoriously bad at this. At first I felt bad for being confused by something so simple. But all their code examples for highlighting refer to their own code and you're right, at the exact moment you're trying to absorb new information it is infuriating to deal with the "meta" examples. I don't use them out of that alone.

This is my main issue with Rspec documentation.