Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

I'd like to review your README

liw.fi

Post reply on HN
Print view View original

51–60 of 94 posts

Re: I'd like to review your README

#51

Post by Omin »

Gadiguibou wrote: post #46
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

The README.md isn't part of the rust code, so it's not checked by this unless you use tools to generate your README from doc comments like https://github.com/livioribeiro/cargo-readme.

Re: I'd like to review your README

#52

Post by astatine »

latexr wrote: post #30
astatine wrote: post #23

Earlier quoted context omitted.

This sounds right, though it doesn't have to be. These type of words signal the author's intent and when 1 - justified by the actual deliverable 2 - substantiated with concrete data can be very useful. They can help create the right expectation. Unfortunately, they are more often misused or abused than applied correctly.

> These type of words signal the author's intent How many people intend to make slow, outdated, insecure software? > when 1 (…) substantiated with concrete data Then show me the data and let me reach my own conclusions. As a bonus point, the unquantifiable adjectives will be removed. > Unfortunately, they are more often misused or abused than applied correctly. Which makes them useless all of the time, because by now…

> How many people intend to make slow, outdated, insecure software? The point is that some authors may claim simplicity, some may claim performance, others more security and so on. It is rare to have all adjectives thrown in - and easy to discard when you see them.

>because by now we’re primed to ignore those claims. Unfortunately, we don't always. If we were ignoring them all, then we wouldn't care. It is that we can't help read and interpret them and have our expectations set up; hence the disappointment when it turned out to be just words.

Re: I'd like to review your README

#53

Post by iudqnolq »

lgreiv wrote: post #20
tirrex wrote: post #18

Earlier quoted context omitted.

fast, simple, scalable, modern, high performance, easy to use, enterprise-grade, secure, production-ready, new generation, lightweight ... These are common words I see in the first paragraph of readmes. If people can avoid these, they’ll write better introductions. No marketing, no subjective words. Otherwise, I feel like someone is trying to sell me that product.

I agree in general, except for `production-ready` which I deem useful information. Of course, it is only the maintainers‘ assessment on the state of the project and thus needs to be validated further by myself. But IMO that adjective signals that I can expect the author to be happy with the current API and behavior and can assume it will be relatively stable; probably battle-tested.

I think "production ready" is essentially impossible without also being able to say "I/my employer/foocorp is running this in production" unless you're not allowed to say it for legal reasons. I think it would take a very experienced developer to predict in advance every issue they'd run into putting something into production.

Re: I'd like to review your README

#54

Post by thejosh »

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.

I like this about elixir, in the documentation you can use exdoc to make sure that the code examples actually work, and provide code samples that are tested. It makes reading documentation for projects quite nice.

Re: I'd like to review your README

#55

Post by tyingq »

"Queue status, in case you’re waiting: 70 in queue, 6 reviewed, oldest in queue: 2021-04-15 13:30 UTC"

Guessing that queue is getting deeper now. Maybe he should add a nominal fee to jump the queue ;)

Re: I'd like to review your README

#56

Post by yboris »

If the repository is of an application, I strongly recommend people include a screenshot of it.

It blows my mind when someone has spent hundreds of hours to make something that they'd like others to use, and didn't spend the 5 minutes needed to increase its use by (my estimate) at least 5%.

Re: I'd like to review your README

#57

Post by MaxBarraclough »

yboris wrote: post #56

If the repository is of an application, I strongly recommend people include a screenshot of it. It blows my mind when someone has spent hundreds of hours to make something that they'd like others to use, and didn't spend the 5 minutes needed to increase its use by (my estimate) at least 5%.

> I strongly recommend people include a screenshot of it

Related: if your project has a website, include a screenshot on the front-page, not buried somewhere. A clickable thumbnail is fine, just don't make the reader work for it.

Might also be worth having a video of the application in action.

Re: I'd like to review your README

#59

Post by an_ko »

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.

I've written this tool to test example code in markdown documents using user-specified shell commands: https://github.com/anko/txm I have had great success using it in my own projects, so perhaps others might find it useful too.
Post reply on HN