4 ms·
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 ma
by yboris 6y ago
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%.
- MaxBarraclough 6y ago> 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.
- daptaq 6y agoThe 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).
- asutekku 6y agoTo 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.
- daptaq 6y agoIMO a valid, human readable README file is will always also generate readable rendered output.
- atleta 6y agoIt'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.
- pcthrowaway 6y agoA 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)
- yboris 6y agoAdding 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.
- k4rli 6y agoPasting to an issue to get an easy image upload is a nice trick, thanks!
- ziml77 6y agoAt least one screenshot is nice. A demo video or GIF is amazing.