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

81–90 of 94 posts

Re: I'd like to review your README

#81

Post by boxed »

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.

You'll like this https://kodare.net/2020/10/23/100_percent_coverage_docs.html it's my journey to 100% coverage for all code samples in ALL the documentation for iommi.

Re: I'd like to review your README

#82

Post by sundarurfriend »

nickjj wrote: post #24

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 i…

Even without detailed comparisons, a "Related projects" section is very useful to the user. Sometimes I see such a section with comments on the other projects like "ProjectA: in case you want features X and Y", or "Project D: emphasises minimalism and configurability", and that is both immensely useful and increases my confidence in the current project whose README I'm looking at. It makes it clear that the author has your best interests in mind and understands their project's strengths and weaknesses.

Re: I'd like to review your README

#83

Post by yboris »

pcthrowaway wrote: post #77
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%.

A good README is unlikely to be 5 minutes of time. I've spent ~5 hours on what I consider "OK" READMEs for our internal projects where I have a captive audience (so don't need to sell them on it)

Adding a screenshot to a README would likely take about 5 minutes. Put your app over a white background, take a screenshot, trim it, paste it in a commend under "Issues" and copy the GitHub-generated shortcode/url for it.

Re: I'd like to review your README

#84

Post by sundarurfriend »

tmotwu wrote: post #27
nickjj wrote: post #21

Earlier quoted context omitted.

> 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…

Zero people have looked at a mission statement like that and thought "Ah, now I understand the scope and limitations of my company, and will use that to direct my ideas".

Re: I'd like to review your README

#85

Post by ChrisMarshallNY »

cdubzzz wrote: post #47

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 ar…

This.

Especially the localization bit. I'm constantly surprised to encounter folks that never even think about it, until version 1.5, and then find out that localization is a nightmare to add, after the fact.

And getting folks to work with them, is just as nightmarish.

Good RoT for localization is native, local speaker of the language, and dialects need to be considered. It's quite possible to bust your ass, getting a Spanish translation, only to have a lot of upset Latin-American users, because the translation was done in Castilian Spanish, as the only person who could handle the tech involved in localization was a CS student in Madrid.

I've learned to factor localization in from the beginning; even if I'm sure that this will never be used outside of my country (which isn't actually fair. There's neighborhoods in Brooklyn, where English is not the primary language; even though everyone was born here).

You just need to get to the point where you have to add localization after the fact –once, to get religion.

Localization is difficult and expensive. If we want people to help us localize, it is incumbent upon us to make it easy and relatively tech-free.

Or we can pay beaucoup bucks to iBabble-On (who do a great job, but not for free).

Re: I'd like to review your README

#86

Post by k4rli »

yboris wrote: post #83
pcthrowaway wrote: post #77

Earlier quoted context omitted.

A good README is unlikely to be 5 minutes of time. I've spent ~5 hours on what I consider "OK" READMEs for our internal projects where I have a captive audience (so don't need to sell them on it)

Adding a screenshot to a README would likely take about 5 minutes. Put your app over a white background, take a screenshot, trim it, paste it in a commend under "Issues" and copy the GitHub-generated shortcode/url for it.

Pasting to an issue to get an easy image upload is a nice trick, thanks!

Re: I'd like to review your README

#87

Post by atleta »

daptaq wrote: post #61
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%.

The issue here is that it is meaningless when viewed locally. GitHub made the mistake of turning "README", a file you'd usually read when you download some code into a website format. A README is broken if lines aren't broken, it is full of badges or nonsense like a table of contents (as OP says, a README is not a manual).

It's not. You can include images in markdown and markdown being markdown, the links are pretty easy to identify and then open.

They don't have to, or better to say the shouldn't, be absolute http links. They can be just relative ones, and those will translate very nicely into file paths locally. If you just use a plain text editor you'll have to open them manually. A bit smarter one (e.g. most likely your IDE) will turn them into clickable file links. You're not losing anything but whoever looks at it on the web will have a lot better idea. And most people will look at it on the web first, before cloning the repo locally... Because it saves time.

Re: I'd like to review your README

#88

Post by ziml77 »

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%.

At least one screenshot is nice. A demo video or GIF is amazing.

Re: I'd like to review your README

#89

Post by m463 »

cdubzzz wrote: post #47

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 ar…

> accessibility and UX audits

I so very much agree. I think user interface design and inconsistency is really holding linux back. Accessibility is intertwined with it.

I think if someone who did game ui design paired with a blind person could critique linux distributions (that led to changes), we would all benefit.

Re: I'd like to review your README

#90

Post by littleninja »

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…

> Does anyone know a community where one can find people to help individually ?

Yes! https://codingcoach.io/

I enlisted to be a mentor but found I wasn’t prepared or ready for the time commitment quite yet. The folks who reach out are often in a bootcamp or self taught and looking for a way to break into their first tech job.

Post reply on HN