Update README and other documentation #711

trey-stafford · 2023-08-07T20:59:07Z

Description

Updates the README for consistency with NSIDC template (main concern being branding - added logos for NSIDC and NSF). Addresses #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].

Config lockfile updated (inv config.export > qgreenland/config/cfg-lock.json)
Version bumped if needed (bumpversion (major|minor|patch|prerelease|build)
CHANGELOG.md updated
Documentation updated if needed
New unit tests if needed

trey-stafford · 2023-08-07T21:19:23Z

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 · 2023-08-07T21:21:54Z

README.md

+# Level of Support
+
+This repository is fully supported by NSIDC. If you discover any problems or
+bugs, please submit an Issue. If you would like to contribute to this


Link to issue page here? Also link to our contributing document? Should we move the contributing section here?

trey-stafford · 2023-08-07T21:22:40Z

README.md

+bugs, please submit an Issue. If you would like to contribute to this
+repository, you may fork the repository and submit a pull request.
+
+See the [LICENSE](LICENSE) for details on permissions and warranties. Please


The LICENSE is called out in the "Level of Support". I thought this had been under its own section, maybe we revised the template.

I honestly don't feel we need to reference the LICENSE in the README at all, but maybe not all would agree.

The file name 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.

If this is the way it is in the template, maybe we should have that discussion via an issue over there.

Yeah, you may be right. This is language taken directly from the template README.

README.md

trey-stafford · 2023-08-07T21:59:26Z

README.md

+contact [email protected] for more information.
+
+
+# Requirements


"Requirements", "Installation", and "Usage" sections are all for QGreenland, not the code here. Is that confusing? The layout of our ReadTheDocs does a good job of distinguishing between user and contributor documentation and includes all of the information here. We should really just have very top-level information here with links to RTD.

Is that confusing?

Yes! I think we should keep the GitHub README focused on being the face of the code, and link out to RTD for user-targeted stuff.

README.md

The 3.16 links give an 'outdated docs' warning. Since 3.28 is our latest supported version, update these paths to reflect that.

Link to actual QGIS documentation page.

* Remove QGreenland plugin as indicated way that QGreenland is delivered. The attention admonition is sufficient. * "Return to QGreenland website" -> "Visit the QGreenland website". This page is linked to from more than just he QGreenland website.

I can't help myself 😆

README.md

MattF-NSIDC · 2023-08-09T22:33:54Z

README.md


-# Getting started
+This repository is fully supported by NSIDC. If you discover any problems or


I think this implies some level of USO engagement. I think we might want to set it to "unsupported" and have a broader discussion about levels of support.

Yeah, good point. Lets think about this some more...I'll see if I can dig up the specifics on when to use each level of service. I hate to put that this isn't supported.

Yes, it would be much better to say "community supported". I brought this up in Slack with @asteiker this week, but she's really busy with IS2 hack week. Maybe will get some feedback on that soon!

I removed this section for now, pending further discussions at NSIDC.

MattF-NSIDC · 2023-08-09T22:40:22Z

README.md

+bugs, please submit an Issue. If you would like to contribute to this
+repository, you may fork the repository and submit a pull request.
+
+See the [LICENSE](LICENSE) for details on permissions and warranties. Please


I honestly don't feel we need to reference the LICENSE in the README at all, but maybe not all would agree.

The file name 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.

If this is the way it is in the template, maybe we should have that discussion via an issue over there.

MattF-NSIDC · 2023-08-09T22:40:41Z

README.md


-## What's inside the QGreenland Core zip package?
+### What is inside the QGreenland Core zip package?


You let this one slide for too long 😆

MattF-NSIDC · 2023-08-09T23:09:09Z

doc/user/reference/data-compatibility-guide.md

+Refer to our documentation page on [Adding New Datasets to
+QGreenland](/user/how-to/adding-data.md) for instructions on how to add new data
+layers to your QGreenland project. Note that this section is also incldued in
+the `UserGuide.pdf` included in the QGreenland Core package.


doc/user/tutorials/video-series-overview.md

MattF-NSIDC · 2023-08-09T23:13:24Z

doc/user/tutorials/video-series-overview.md

-If you are not familiar with geographic information systems (GIS) and geospatial data, this video will introduce you to GIS and what it can be used for.
-### [Session 1: Introduction to QGreenland](https://www.youtube.com/watch?v=gD0vkP5JUmA&list=PLSRiyMridUCwyu-vqpAFtm8bVERgTvs7q&index=1)
+If you are not familiar with geographic information systems (GIS) and geospatial
+data, this video will introduce you to GIS and what it can be used for.


doc/what_is_qgr.md

MattF-NSIDC · 2023-08-09T23:15:27Z

doc/what_is_qgr.md

-   (for example, due to filesize constraints). QGreenland Custom has its own
-   [documentation](https://qgreenland-plugin.readthedocs.io).
+```{attention}
+The QGIS Plugin **[QGreenland Custom](https://plugins.qgis.org/plugins/qgreenland/)


I like this much better!

Co-authored-by: Matt Fisher <[email protected]>

We want to direct those who want to use QGreenland Core to our website.

Co-authored-by: Matt Fisher <[email protected]>

Should be obvious that qgr core is required to look at layer metadata. We do a good job of directing users to the 'right' starting place already. The info about the tutorial is better suited for a note.

We need some updated guidance on when/how to set the LoS. This is primarily for tools supported by USO, which we don't really expect for QGreenland.

trey-stafford · 2023-08-14T20:44:48Z

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.

Co-authored-by: Matt Fisher <[email protected]>

MattF-NSIDC · 2023-08-14T21:03:55Z

doc/user/how-to/metadata.md

+
+```{note}
+To see the layer's geospatial metadata (e.g., the coordinate reference system
+and spatial extent), we recommend [using QGIS](#via-qgis-layer-properties).


These anchor links can be broken easily if someone changes the title of the section. If we use an explicit cross-reference, these links are more durable and can throw errors at build time if we break either end of the crossref!

https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#explicit-targets

Nice, I'll take a look at this! Note that our build process already produces an error if one of these links is broken (at least within single pages)

Oh cool, I thought it just skipped checks for this style of link.

I think it's just http links that get skipped. I replaced a bunch with references #like-this in other parts of this PR. In a couple of cases I changed a title without the #like-this link, and our build process thew an error indicating where those broken links were.

Issue to address this more holistically: #723

trey-stafford added 3 commits August 7, 2023 14:57

Add NSIDC and NSF logos to README

c1b6089

Sections for level of support, installation, usage, and troubleshooting

5143fff

Link to documentation page for usage section

5d51c39

trey-stafford commented Aug 7, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

trey-stafford linked an issue Aug 7, 2023 that may be closed by this pull request

Update/review README for consistency w/ nsidc repo template #687

Closed

trey-stafford added 2 commits August 7, 2023 15:55

Link to github issues

9aced42

Link to contributing section from "level of support"

7caa2b7

trey-stafford commented Aug 7, 2023

View reviewed changes

trey-stafford added 4 commits August 7, 2023 16:17

remove redudant content about what's included in QGreenland

7e5d4dd

Link to "What is QGreenland" page in description

de5c6c7

Tweak disclaimer text

348b32f

Move QGIS supported versions to get-started tutorial.

f04a4b8

trey-stafford commented Aug 7, 2023

View reviewed changes

README.md Show resolved Hide resolved

trey-stafford added 14 commits August 7, 2023 16:40

Fixup broken link

1b3d486

Move disclaimer to page on RTD

f3afcc5

docs: relative link to RTD page

7553ed7

Fix link in video series overview

12d0ab9

Link title + formatting

a76f27b

Fixups and improvements for the qgreenland beginner series tutorial

6354f2a

Update QGIS docs refs from v3.16 -> v3.28

05e249f

The 3.16 links give an 'outdated docs' warning. Since 3.28 is our latest supported version, update these paths to reflect that.

Update note about temporal controller

cb17c26

Link to actual QGIS documentation page.

Remove unnecessary new lines

3a4efec

Remove user installation instructions from README

04a50f5

Tweaks for "what is qgr" doc pageo

4a2f95e

* Remove QGreenland plugin as indicated way that QGreenland is delivered. The attention admonition is sufficient. * "Return to QGreenland website" -> "Visit the QGreenland website". This page is linked to from more than just he QGreenland website.

formatting

768a6bc

Merge branch 'main' into update-readme-nsidc-template

c6fca01

Remove text about the future of QGreenland custom using 'modules'

09535f4

trey-stafford added 2 commits August 9, 2023 12:23

what's -> what is

5a3ca42

I can't help myself 😆

Fixup link

360a157

trey-stafford changed the title ~~Update README for consistency with NSIDC template.~~ Update README and other documentation Aug 9, 2023

trey-stafford marked this pull request as ready for review August 9, 2023 19:47

MattF-NSIDC reviewed Aug 9, 2023

View reviewed changes

MattF-NSIDC mentioned this pull request Aug 10, 2023

Add layer quality checklist to contributor docs #716

Merged

5 tasks

trey-stafford and others added 13 commits August 10, 2023 08:41

Update doc/user/tutorials/video-series-overview.md

69351a3

Co-authored-by: Matt Fisher <[email protected]>

Update README.md

f618dbc

Co-authored-by: Matt Fisher <[email protected]>

Update README.md

baaa5c8

Co-authored-by: Matt Fisher <[email protected]>

Update README.md

ba7fb53

Co-authored-by: Matt Fisher <[email protected]>

Update README to make repo responsibilities clear

740b770

We want to direct those who want to use QGreenland Core to our website.

Attempt to force README logos to be same size

f53e2ed

Move badges below title

116b910

Add CODE_OF_CONDUCT

d86d5f5

Capitalize word

2003968

Co-authored-by: Matt Fisher <[email protected]>

Clarify link text

5822d62

Co-authored-by: Matt Fisher <[email protected]>

Fixup spelling

ab4caa7

Co-authored-by: Matt Fisher <[email protected]>

! -> .

42559b4

Co-authored-by: Matt Fisher <[email protected]>

Replace note about downloading qgr w/ info about tutorial

3e55c05

Should be obvious that qgr core is required to look at layer metadata. We do a good job of directing users to the 'right' starting place already. The info about the tutorial is better suited for a note.

trey-stafford mentioned this pull request Aug 11, 2023

Update video-series-overview.md #722

Merged

7 tasks

Remove Level of Support section, for now

c65d456

We need some updated guidance on when/how to set the LoS. This is primarily for tools supported by USO, which we don't really expect for QGreenland.

trey-stafford and others added 2 commits August 14, 2023 14:45

Tweak language about scope of users

d791b50

Co-authored-by: Matt Fisher <[email protected]>

Update how-to: add note about geospatial metadata

06abc3c

MattF-NSIDC reviewed Aug 14, 2023

View reviewed changes

Explicit reference

d540657

MattF-NSIDC approved these changes Aug 14, 2023

View reviewed changes

trey-stafford merged commit 0eb2e9d into main Aug 14, 2023
2 checks passed

trey-stafford deleted the update-readme-nsidc-template branch August 14, 2023 21:31

trey-stafford mentioned this pull request Aug 14, 2023

Link to contributor documentation from GitHub README #607

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update README and other documentation #711

Update README and other documentation #711

trey-stafford commented Aug 7, 2023 •

edited

Loading

trey-stafford commented Aug 7, 2023

trey-stafford Aug 7, 2023

trey-stafford Aug 7, 2023 •

edited

Loading

MattF-NSIDC Aug 9, 2023

trey-stafford Aug 10, 2023

trey-stafford Aug 7, 2023

MattF-NSIDC Aug 7, 2023

MattF-NSIDC Aug 9, 2023

trey-stafford Aug 10, 2023

MattF-NSIDC Aug 10, 2023

trey-stafford Aug 14, 2023

MattF-NSIDC Aug 9, 2023

MattF-NSIDC Aug 9, 2023

MattF-NSIDC Aug 9, 2023

MattF-NSIDC Aug 9, 2023

MattF-NSIDC Aug 9, 2023

trey-stafford commented Aug 14, 2023

MattF-NSIDC Aug 14, 2023

trey-stafford Aug 14, 2023

MattF-NSIDC Aug 14, 2023

trey-stafford Aug 14, 2023

trey-stafford Aug 14, 2023

MattF-NSIDC Aug 14, 2023

		contact [email protected] for more information.


		# Requirements


		# Getting started
		This repository is fully supported by NSIDC. If you discover any problems or


		## What's inside the QGreenland Core zip package?
		### What is inside the QGreenland Core zip package?

Update README and other documentation #711

Update README and other documentation #711

Conversation

trey-stafford commented Aug 7, 2023 • edited Loading

Description

Checklist

trey-stafford commented Aug 7, 2023

Choose a reason for hiding this comment

trey-stafford Aug 7, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trey-stafford commented Aug 14, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trey-stafford commented Aug 7, 2023 •

edited

Loading

trey-stafford Aug 7, 2023 •

edited

Loading