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

21–30 of 94 posts

Re: I'd like to review your README

#21

Post by nickjj »

DandyDev wrote: post #15

Great initiative and very generous! My pet peeve with READMEs: usage of excessive adjectives to oversell your project. Famous culprits: "blazingly fast" or software that is "beautiful" or creates "beautiful" things.

> My pet peeve with README

DHH had a funny line around Dropbox's "mission" in his 2019 railsconf video (linked to the direct point in the video): https://youtu.be/VBwWbFpkltg?t=2818

Dropbox's official mission as of 2019 was: "We're here to unleash the world's creative energy by designing a more enlightened way of working"

And DHH's remark was: "For fuck's sake Dropbox, you host files and make them appear on all of my computers"

Funny enough since then they changed their mission to be "Our mission is to design a more enlightened way of working" based on https://www.dropbox.com/about but it still doesn't come close to explaining what they do.

Re: I'd like to review your README

#23

Post by astatine »

tirrex wrote: post #18
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.

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.

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.

Re: I'd like to review your README

#24

Post by nickjj »

Beyond covering the "why" and the problem your tool solves it's also IMO a really good idea to include a "why use this over XYZ" section if your tool happens to have a few popular alternative libraries or is similar to something that most folks in your niche already knows.

Because if your tool is new, one of the first things folks are going to think is "why wouldn't I continue using XYZ?". The goal of this question isn't to put down the competition but it should draw comparisons between the tools and include the reasons why you created your tool. This could be adding certain features, doing things faster or whatever makes sense.

Flask-Classful's docs https://flask-classful.teracy.org/ has an excellent example of the above. The opening paragraphs cover it so well. The rest of the docs are also a good baseline example for creating useful documentation. Lots of practical code examples with very clear explanations of how it works.

Re: I'd like to review your README

#25

Post by ChrisMarshallNY »

polote wrote: post #14

> I’d like to help others make better free and open source software so I’m making this standing offer: I’ll review your README for free. On a more global discussion, I feel like a lot of experienced people are willing to help, or teach for free on subjects such as, startups, programming, product management, data science, tech subjects ... (and I assume on other non-tech topics also) but it is always hard to find peop…

As an older person that has done quite a bit of free teaching, I'd gently suggest that a good start would be to have the current generation be a little more generous towards us.

A lot of us are, indeed, tiresome old "OK boomers," but some of us (I'd like to think I'm one) may actually have something to contribute.

Here's an example of a simple course I gave on Core Bluetooth. It was not free, but try! Swift World does their courses for $50 a pop, which is pretty cheap (BTW: I donated the proceeds for my class to sponsor scholarships to other classes): https://www.linkedin.com/posts/chrismarshallny_try-swift-wor...

Take note of the course materials. They basically teach the class on their own (also, they are entirely driven by some very intense READMEs).

In my experience, a couple of the better teachers on try! Swift World are relatively older ones, like Erica Sadun and Daniel Steinberg. Some of the younger ones are also excellent.

Re: I'd like to review your README

#26

Post by hobofan »

I think that's a great service for projects that want more users (whether that's a good idea/goal is another topic)!

On my own projects I've seem a pretty clear divide in adoption between projects which have a good README (100+ stars) and projects which have a similar level of utility/maturity but where I didn't bother to write a proper README (0-5 stars). (Stars are often a bad proxy for adoption, but here they are roughly proportional to downloads, reported issues, etc.)

Re: I'd like to review your README

#27

Post by tmotwu »

nickjj wrote: post #21
DandyDev wrote: post #15

Great initiative and very generous! My pet peeve with READMEs: usage of excessive adjectives to oversell your project. Famous culprits: "blazingly fast" or software that is "beautiful" or creates "beautiful" things.

> My pet peeve with README DHH had a funny line around Dropbox's "mission" in his 2019 railsconf video (linked to the direct point in the video): https://youtu.be/VBwWbFpkltg?t=2818 Dropbox's official mission as of 2019 was: "We're here to unleash the world's creative energy by designing a more enlightened way of working" And DHH's remark was: "For fuck's sake Dropbox, you host files and make them appear on all of my…

Customers don’t infer the purpose of a product from it’s company mission. The audience of a company mission are employees themselves. Dropbox has expanded to more than file syncing over the past decade. It makes sense to have a broad vision of their future, e.g purposeful mission.

Imagine Amazon telling employees to stick it to books because thats the business they started off with. Like why should AWS even exist, it’s not what they do! That narrow mindedness wouldn’t have gotten them to where they are today.

Re: I'd like to review your README

#28

Post by [deleted] »

polote wrote: post #14

> I’d like to help others make better free and open source software so I’m making this standing offer: I’ll review your README for free. On a more global discussion, I feel like a lot of experienced people are willing to help, or teach for free on subjects such as, startups, programming, product management, data science, tech subjects ... (and I assume on other non-tech topics also) but it is always hard to find peop…

[deleted]

Re: I'd like to review your README

#29

Post by nickjj »

tirrex wrote: post #18
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.

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 think production ready on its own has value because it sets the stage of what to expect.

There's a very big difference between a project being production ready or not. Production ready (to me at least) means the project has been thoroughly tested on a live site and is in a position where you can take it as is and run it in production with confidence that it's going to work.

For example I have a Docker + Flask example starter kit project at https://github.com/nickjj/docker-flask-example and the GitHub description is "A production ready example Flask app that's using Docker and Docker Compose.". In this context to me that says it's using multi-stage builds, env variables, deals with static files in a way that's cacheable (md5 hashes, etc.), has tests and overall you can expect to see patterns that work well in both dev and prod. The README goes over those details too in case you didn't infer that from only "production ready" too.

Plot twist: It took me longer to write the README than create the whole project.

Re: I'd like to review your README

#30

Post by latexr »

astatine wrote: post #23
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.

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 we’re primed to ignore those claims.

Post reply on HN