I'd like to review your README

Re:I'd like to review your README by nooyurrsdey on Saturday April 17, 2021 @08:24AM (#26843736)

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.

[ Parent | on HN ]

Re:I'd like to review your README by erikerikson on Saturday April 17, 2021 @10:57AM (#26844669)

You have a point and I might reprioritize.

Specialized terminology allows the communication of complex concepts compactly. For the specialists a brief description like you mentioned is perfect. If you give it first, that person can read it and decide.

It should certainly be followed by a tear down or other plain English explanation of what the thing is.

Kind of like: ``` Brief

A little longer

Be descriptive about the thing

Go into every detail you want to discuss about the thing in the repository... ```

The jargon fooled blurb makes a great "a little longer" and gets out of the way to let the more readable description be given. Burying that can be a pain.

[ Parent | on HN ]

Re:I'd like to review your README by bloopernova on Saturday April 17, 2021 @12:06PM (#26845276)

That's a really good point.

I need to either find or write a good readme template with that in mind.

[ Parent | on HN ]