Open source devs: please, please add screenshots...

Although I understand the OP's perspective open-source is a community effort and people should have a more proactive attitude and contribute when they feel things aren't okay. Most open-source developers aren't focused / don't have time for how things look (or at least not on the beginning). If you're a regular user and you can spend an hour taking a bunch of screenshots and improving a readme you'll be making more for the future the project that you might think.

As both user and developer - user CAN contribute but the developer/maintainer SHOULD add the screenshots.

This mentality explains a lot of open source.

There's both an ignorance and fear barrier to that.

A lot of people don't know they can, and don't know how. And even the ones that do know, often worry their contributions would be shit.

And there's folks that just don't think the project would accept that kind of submission.

I'm not contradicting your suggestion! It's a great thing to let people know that they can contribute without knowing how to code. Just adding in both an explanation as to why it's so rare, and hopefully allaying some of those worries for passersby.

If the app sucks, few people will add the screenshots. Therefore, most apps without screenshots will suck. So new apps will need the developer to add screenshots, or people will assume it sucks.

And we're back to square one. The developer has extra responsibility to highlight the features.

This is good advice, but having a screenie there in the first place might make someone more likely to try it out.

One thing though: I’m likely not to stop and consider looking closer at an app if I can’t judge if it’s going to be what I’m looking for. I’m not going to go over random GitHub repositories and create screenshots for their projects. So if the assumption is that the user contributes screenshots I don’t think it will ever change anything for the majority of projects.

This. It should be the most sane configuration and fit most use cases and lead to an experience working out of the box.

There's a real problem here with backwards compatibility. If you add an option for something, it makes sense to make the default match the functionality of old versions, even if it's not the best for general use cases. That way any tools built on top of it can safely update.

I prefer the simple, sane defaults that work for everyone with a heavily commented config file giving detailed information on what each value for each option does, personally. Like MPV's config file.

Krita and not having hotkeys ಠ_ಠ

Foreplay is important! Gotta get me excited for that app.

A lot of documentation is like that.

Its terrible when the software is called some random word that has nothing to do with the programs functionality

To be that dick, a headless component library is still meant to do something, show an example of it being used!

If you've written a "usage" section that showcases more than one uselessly simple example that doesn't even work in the project's current state, you're already far ahead of the average.

Even for a CLI tool, there should be a real world example showing how it works and what the output looks like. Eg, for jq:

$ cat file.json
{"field: "value"}
$ jq '.field' file.json
"value"

And a few other examples.

It scroobles obviously!

Including the documentation link, which only has incomplete getting started section

TODO

I imagine most single developer projects lack any design or UX so the screenshot would do little to encourage users to download.

I wish there was a way to give more props to open-source repos that do this.

I already star the project. But I'd love to say "Thanks for making a demo page it really helped!"

Get to it, mate! You can do it!

It's easier said than done for sure

On github you can even paste your screenshot right from the clipboard. Zero excuses for not having a screenshot.

GitHub and GitLab both support inserting images into your README.md. Here's the syntax:

![Description of the image](https://path/to/image)

Not just a text file, a markdown file. And markdown has supported images since forever

README.txt will be a text file, README.md can be much more

I find this unnecessarily derisive. There are good reasons for a UI or README not being user-friendly, the top-most one being (imo) that it is really, really hard to get right, takes a lot of time and doesn't primarily solve the problem the project was started for.

I don’t care; you’re not my intended audience.

That's pretty ignorant

Where: In the repository, most projects seem to use media or screenshots as the name of the directory.

How often: Whenever a big change happened or many small changes have accumulated.

What: Light theme suffices. I only care about the general look and feel, not about specific colors.

That’s how I would do it for my own projects.

That’s one option, or use imgur.

Update them if your UI has significantly changed or does not adequately represent the final product.

If having a light/dark theme is an important feature or highly requested feature for your project, it would be nice to show it off.

Screenshots can, most of the time, get away with showing just the default configuration. Share what a user would see when opening your project for the first time, and assume they used the default configuration. Optionally, if you offer a lot of customization, show what it could look like if someone spent a good amount of time personalizing things!

Yes. Git can store binary files fine. It's not the most efficient for storing them, but it works, especially for a small number of screenshots. For updating and theme, that's entirely up to you. It's all a judgement call. If you want to show off your functionality (like a dark mode), I encourage you to include screenshots of it. If you substantially change your UI, update the images.

You don't have to update for every new button you add. It's more about giving a general impression of the UI. Is it minimalist? Is it a chaotic mess? Does it look like it fits in naturally with whatever OS appears to have been used? Does it look like any thought was put into UI and UX? Those are the kinds of things you're trying to answer.

UI is always the main focus for the user. Because it's the "User Interface".

Searching the web for screenshots is an added hassle and something that makes me avoid most FOSS software, because sometimes there's not enough screenshots and not even the developer cared to show what the app is about.

I think that doesn't work for most smaller projects. That'll work for something like Firefox, but there's little reason for random, unheard of tools to have an image on the web. Plus the naming of some projects is super generic, which can make it hard to find correct images.

Some software changes appearance often, too, and google is bad at knowing what up to date is. It can be really easy to find wildly out of date images as the top results.

README markdown files allow for inline image links to be "expanded"

For a lot of open source at the moment the root level readme is fundamentally the homepage too. It absolutely should include screenshots, maybe even a gif. If your software has a GUI or TUI it should follow that a concise visual will do more to explain it's usage than a text document

Unironically yes. Asking someone that doesn't use your project, isn't part of the development, and quite possibly doesn't even want anything to do with your project to do work for you project is silly.

I mean, it's just a suggestion. The utility depends on the goal of the project. Am I being lazy? Don't care. Do I want maximum user engagement/feedback; well, the suggestion is sound.

So why not add a 'Screenshots' section with hyperlinks to PNG files?

I mean, yes, it's a little more effort, but I think you're over playing how much effort is required. Writing a half decent readme is vastly easier than frankly any feature or bug fix. Taking a couple of notable screenshots is super easy. Writing docs is hard (I've written tons for large and complicated projects), but readmes are the easiest and including screenshots is really quite easy.

Everywhere supports markdown in readmes now. Literally everywhere I've ever hosted code. And markdown with links to images is perfectly fine even if viewed in plain text mode. They'll just click the link and view the image standalone. I've done that plenty of times, too. Every editor (plus in-browser code hosts in plain text mode) makes it easy.

it's the very first thing you see when you visit any project's github page.

Lots of projects are on GitHub or similar repositories and the landing page is usually the readme file as rendered markdown.

I appreciate your joke, I totally got if.

Mainly because my dad would do exactly that if he ever had to use github lol. I grew up watching him literally throw manuals aside, only to have me or my sister bring them back when he screwed up lol.

a.) I'm not convinced you know what the word hypocrite means.

b.) More importantly, they didn't ask for "numerous," they asked for one.

c.) Searching for the UI on, say Google, can have, at best, mixed results. Ive done this, then DLed and tried out the program only to find a completely different UI.

d.) The dev adding one screenshot to their readme.md and a /media folder takes them only slightly longer than it takes potential users to look one up and maybe get a good result. Multiply that time by the number of potential users, and it's obviously more efficient, and effective, for the dev to do it.

Stop being defensive. No one's attacking you or any other dev. They're making a request. Don't like it? Don't do it. Stop calling people names and trying to stir up drama.

Edit: formatting