Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README and other documentation #711

Merged
merged 59 commits into from
Aug 14, 2023
Merged

Update README and other documentation #711

Changes from 8 commits
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
c1b6089
Add NSIDC and NSF logos to README
trey-stafford Aug 7, 2023
5143fff
Sections for level of support, installation, usage, and troubleshooting
trey-stafford Aug 7, 2023
5d51c39
Link to documentation page for usage section
trey-stafford Aug 7, 2023
9aced42
Link to github issues
trey-stafford Aug 7, 2023
7caa2b7
Link to contributing section from "level of support"
trey-stafford Aug 7, 2023
7e5d4dd
remove redudant content about what's included in QGreenland
trey-stafford Aug 7, 2023
de5c6c7
Link to "What is QGreenland" page in description
trey-stafford Aug 7, 2023
348b32f
Tweak disclaimer text
trey-stafford Aug 7, 2023
f04a4b8
Move QGIS supported versions to `get-started` tutorial.
trey-stafford Aug 7, 2023
1b3d486
Fixup broken link
trey-stafford Aug 7, 2023
f3afcc5
Move disclaimer to page on RTD
trey-stafford Aug 7, 2023
7553ed7
docs: relative link to RTD page
trey-stafford Aug 7, 2023
12d0ab9
Fix link in video series overview
trey-stafford Aug 7, 2023
a76f27b
Link title + formatting
trey-stafford Aug 7, 2023
6354f2a
Fixups and improvements for the qgreenland beginner series tutorial
trey-stafford Aug 7, 2023
05e249f
Update QGIS docs refs from v3.16 -> v3.28
trey-stafford Aug 8, 2023
cb17c26
Update note about temporal controller
trey-stafford Aug 8, 2023
3a4efec
Remove unnecessary new lines
trey-stafford Aug 8, 2023
04a50f5
Remove user installation instructions from README
trey-stafford Aug 8, 2023
4a2f95e
Tweaks for "what is qgr" doc pageo
trey-stafford Aug 8, 2023
768a6bc
formatting
trey-stafford Aug 8, 2023
c6fca01
Merge branch 'main' into update-readme-nsidc-template
trey-stafford Aug 8, 2023
09535f4
Remove text about the future of QGreenland custom using 'modules'
trey-stafford Aug 8, 2023
75a5284
Data compatibility guide: link to documentation page
trey-stafford Aug 8, 2023
3786f58
Adding-data how-to: update text around adding new layers to qgis
trey-stafford Aug 8, 2023
872e63a
Clarify name of section about selecting for greenaland-specific data
trey-stafford Aug 9, 2023
8c17ab8
Move & update section on creating custom clipping boundary polygon
trey-stafford Aug 9, 2023
8b3ea4e
update section on adding new vector layers
trey-stafford Aug 9, 2023
364462e
Cleanup trailing whitespaces
trey-stafford Aug 9, 2023
5b708e8
Fixup references
trey-stafford Aug 9, 2023
66ed05e
Remove some contractions (e.g., `you're` -> `you are`) from docs
trey-stafford Aug 9, 2023
06855fb
Significantly simplify GPS how-to guide.
trey-stafford Aug 9, 2023
5d8f42b
Fixup heading position (swap newline)
trey-stafford Aug 9, 2023
c1a08b8
`that's` -> `that is`
trey-stafford Aug 9, 2023
51d977c
`it's` -> `it is`
trey-stafford Aug 9, 2023
18452bc
Move note about qgr project crs
trey-stafford Aug 9, 2023
e001a35
Metadata how-to: remove reference to qgreenland custom
trey-stafford Aug 9, 2023
6038fe4
Replace plugin tutorial w/ discussion page.
trey-stafford Aug 9, 2023
dcf24a3
Remove "How-tos" section from contributing discussion
trey-stafford Aug 9, 2023
27edfe8
Further updates to README, contributor docs
trey-stafford Aug 9, 2023
5a3ca42
`what's` -> `what is`
trey-stafford Aug 9, 2023
360a157
Fixup link
trey-stafford Aug 9, 2023
69351a3
Update doc/user/tutorials/video-series-overview.md
trey-stafford Aug 10, 2023
f618dbc
Update README.md
trey-stafford Aug 10, 2023
baaa5c8
Update README.md
trey-stafford Aug 10, 2023
ba7fb53
Update README.md
trey-stafford Aug 10, 2023
740b770
Update README to make repo responsibilities clear
trey-stafford Aug 10, 2023
f53e2ed
Attempt to force README logos to be same size
trey-stafford Aug 10, 2023
116b910
Move badges below title
trey-stafford Aug 10, 2023
d86d5f5
Add CODE_OF_CONDUCT
trey-stafford Aug 10, 2023
2003968
Capitalize word
trey-stafford Aug 10, 2023
5822d62
Clarify link text
trey-stafford Aug 10, 2023
ab4caa7
Fixup spelling
trey-stafford Aug 10, 2023
42559b4
! -> .
trey-stafford Aug 10, 2023
3e55c05
Replace note about downloading qgr w/ info about tutorial
trey-stafford Aug 10, 2023
c65d456
Remove Level of Support section, for now
trey-stafford Aug 14, 2023
d791b50
Tweak language about scope of users
trey-stafford Aug 14, 2023
06abc3c
Update how-to: add note about geospatial metadata
trey-stafford Aug 14, 2023
d540657
Explicit reference
trey-stafford Aug 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 52 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
<p align="center">
<img alt="NSIDC logo" src="https://nsidc.org/themes/custom/nsidc/logo.svg" width="150" />
<img alt="NSF logo" src="https://nsidc.org/sites/default/files/images/Logo/NSF.svg" width="150" />
</p>
trey-stafford marked this conversation as resolved.
Show resolved Hide resolved

[![NSF-1928393](https://img.shields.io/badge/NSF-1928393-red.svg)](https://nsf.gov/awardsearch/showAward?AWD_ID=1928393)
[![DOI](https://zenodo.org/badge/241453043.svg)](https://zenodo.org/badge/latestdoi/241453043)

Expand All @@ -15,22 +20,24 @@

## A Free GIS package for Greenland
trey-stafford marked this conversation as resolved.
Show resolved Hide resolved

QGreenland is a free mapping tool to support interdisciplinary
Greenland-focused research, teaching, decision making, and collaboration.

Combines key datasets into a unified, all-in-one GIS analysis and visualization
environment for offline and online use.
QGreenland is a free mapping tool to support interdisciplinary Greenland-focused
research, teaching, decision making, and collaboration. It combines key datasets
into a unified, all-in-one GIS analysis and visualization environment for
offline and online use.

An international Editorial Board and Project Collaborators connects the
QGreenland Team to data and user communities.

Learn more about [What is
QGreenland?](https://qgreenland.readthedocs.io/en/latest/what_is_qgr.html)


## Disclaimer

QGreenland should not be used as a sole navigational aid while performing
remote research activities in Greenland. Always bring appropriate safety and
navigational aids (including hard-copies of topographic maps) when visiting the
field.
QGreenland should not be used as a sole navigational aid while performing remote
research activities in Greenland or elsewhere. Always bring appropriate safety
and navigational aids (including hard-copies of topographic maps) when visiting
the field.

QGreenland is a data-viewing and analysis platform, and the QGreenland Team does
not create new data. QGreenland's layers may contain errors from the original
Expand All @@ -48,7 +55,18 @@ on any transformations. All QGreenland GeoPackages and GeoTIFFs are projected
in `EPSG:3413`.


# Getting started
# Level of Support

This repository is fully supported by NSIDC. If you discover any problems or
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

bugs, please submit an [Issue](https://github.com/nsidc/qgreenland/issues). If
you would like to contribute to this repository, please see the section on
[Contributing](#Contributing).

See the [LICENSE](LICENSE) for details on permissions and warranties. Please
Copy link
Contributor Author

@trey-stafford trey-stafford Aug 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

contact [email protected] for more information.


# Requirements
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


As of this writing, the oldest version of QGIS we support for the QGreenland release
series are:
Expand All @@ -57,7 +75,10 @@ series are:
* QGreenland `2.x`: QGIS `3.16.x LTR`
* QGreenland `3.x`: QGIS `3.28.x LTR`

You can find downloads and instructions

# Installation

You can find downloads and instructions for downloading QGIS
[here](https://qgis.org/en/site/forusers/download.html).

After installing QGIS, [download QGreenland](https://qgreenland.org/download)
Expand All @@ -71,22 +92,25 @@ Finally double-click on (or use QGIS open) the `qgreenland.qgs` file that was ju
extracted from the zip.


# Usage

Please see our [documentation](https://qgreenland.readthedocs.io) for detailed
usage instructions. The [Get started with QGreenland
Core](https://qgreenland.readthedocs.io/en/latest/user/tutorials/get-started.html)
tutorial is a good starting point for new users.

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

At the root of the zip file, you will find scientific discipline-specific directories
containing data (GeoTIFFs and GeoPackages). Additionally, the following files are
present at the package root:
At the root of the zip file, you will find useful files such as a
`UserGuide.pdf`, the `qgreenland.qgs` QGIS project file and scientific
discipline-specific directories containing data (GeoTIFFs and GeoPackages).

* `UserGuide.pdf`: Detailed user-guide.
* `QuickStartGuide.pdf`: Guide for QGIS beginners.
* `README.html`: The README file you are currently reading.
* `CHANGELOG.html`: A summary of changes for each new QGreenland version.
* `layer_list.csv`: Comma-separated values representing the configuration of
layers in QGreenland. This includes limited layer metadata, including, but not limited
to: title, description, abstract, and citation.
For more detailed information, see our documentation on the [QGreenland Core
Download
Package](https://qgreenland.readthedocs.io/en/latest/what_is_qgr.html#qgreenland-core-download-package).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love it



# Educational resources
## Educational resources

We keep the QGreenland official website up-to-date with links to helpful
educational resources, including our own QGreenland User Guide.
Expand All @@ -96,6 +120,12 @@ educational resources, including our own QGreenland User Guide.
* [QGreenland official documentation](https://qgreenland.readthedocs.io)


# Troubleshooting

See our user troubleshooting guide
[here](https://qgreenland.readthedocs.io/en/latest/user/how-to/troubleshooting.html).


# Contributing

Please see [contributing
MattF-NSIDC marked this conversation as resolved.
Show resolved Hide resolved
Expand Down