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).
To be fair, i haven’t read a local readme in years. Markdown in github is hands down miles better and provides more value than any local readme openable with any kind of computer could provide.
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.
> 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.
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.
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%.