nsidc / qgreenland

Source code for generating the QGreenland package hosted at https://qgreenland.org/
https://qgreenland.readthedocs.io
Other
36 stars 9 forks source link

Update README and other documentation #711

Closed trey-stafford closed 11 months ago

trey-stafford commented 11 months ago

Description

Updates the README for consistency with NSIDC template (main concern being branding - added logos for NSIDC and NSF). Addresses https://github.com/nsidc/qgreenland/issues/687.

I ended up down a bit of a documentation rabbit-hole here. As I was updating the README, a major goal was to condense the information there and place most of the responsibility for explaining e.g., contributing and usage information, on the ReadTheDocs docs.

As I started to link from the README to other parts of the documentation, I found other issues (broken links, wonky formatting, incorrect (outdated) information for QGIS 3.28, etc.) that ended up getting fixed here.

Checklist

If an item on this list is done or not needed, simply check it with [x].

trey-stafford commented 11 months ago

Mainly concerned with making sure we have the logos (particularly the NSIDC logo) present.

Are the other changes worthwhile? Calling out the LICENSE seems like a good idea.

The "Level of Support" section is a little awkward...it contains some contributing guidance. Should the contributing section move to under "Level of Support"?

trey-stafford commented 11 months ago

The conversation is 'outdated' becuase it was part of the LoS that I removed, but responding to this quote @MattF-NSIDC made:

The file name [LICENSE] is all-caps, so it's practically already screaming at me, and GitHub automatically recognizes the file and displays a special link for it anyway.

The link is the key part here. I see a "View license" link that links to our LICENSE. However, we shouldn't necessarily count on individuals seeing a file in the directory listing. When viewing a repo from a mobile browser, for example, GH hides the repo's content and just shows the README by default.