search

embedded-graphics / examples

Embedded graphics examples
Apache License 2.0
26 stars 5 forks source link

Improved README #5

Open rfuest opened 3 years ago

rfuest commented 3 years ago

What should be added to the README for this repo? I would suggest to add some basic information on how to run the examples. Should we also add a list of examples and a short description of each one or is the list of files enough?

jamwaffles commented 3 years ago

Yep, some basic info would be great.

If it's possible to do without too much infrastructure, auto-generating that list straight into README.md would be ideal, but if not maybe it's a better idea to just point people to the examples/ folder?

rfuest commented 3 years ago

I would suggest to start with a simple link and maybe update it to an auto-generated list later. Perhaps we could also include a montage of some screenshots to make the README look more interesting.

Could you add a some basic info to the README and also setup CI (#4)?

jamwaffles commented 3 years ago

Sure!

rfuest commented 3 years ago

How should we handle the README(s) with the new repo structure? Should we only have a toplevel README that links to eg-{{version}}/examples directories? Or should each eg-{{version}} directory have a separate README? We could also add a README.md to the examples directories instead of the crate roots, this way the user would get a file list and additional information (e.g. how to run the examples) at the same time.

jamwaffles commented 3 years ago

It would be useful to have both I think - that way direct links into each folder get a good overview, and people who land on the root page will also see some actionable links. It's more maintenance work, but some of it could be automated with some templates.

bugadani commented 3 years ago

I'm a bit unsure about the example images' alt texts. I don't think they are descriptive at all and I think it would make more sense to approach alt text from an accessibility point of view: describe what's on the image, not which example is used to draw it. The latter piece of information is pretty much straight forward from the readme itself.