From a36463cb3b37bcb5a4f9880aa5fbaff85d3e1d04 Mon Sep 17 00:00:00 2001 From: Hugh Rundle Date: Tue, 26 Jan 2021 18:42:37 +1100 Subject: [PATCH] update docs Now that that the merging GitHub Action is working, the docs need to be updated in regard to the geojson and topojson files. Also cleans up where this info is located, as it was in 'about' but should be in 'contributing'. --- about.md | 13 +++---------- contributing.md | 6 +++--- website/contributing/index.html | 2 +- 3 files changed, 7 insertions(+), 14 deletions(-) diff --git a/about.md b/about.md index c27e23c..e629f88 100644 --- a/about.md +++ b/about.md @@ -54,15 +54,8 @@ If this naming convention is confusing, you may view the map in *Colonial mode*, Standard Mode invites you to think about the work these institutions do to normalise certain types of knowledge and not others. -### Important files that are not in this repository +### Important file that is not in this repository -If you look at `merge_service_data.py` you will notice that there are two files used in creating `website/data/boundaries.topo.json` that are missing from this repository: +The "core" geojson file with boundaries for each library service is not in the repository. The only other data it holds is the name of each area. When boundaries need to be changed for some reason (a regional library service de-merges, for example), this file needs to be updated using GQIS, and then processed into TopoJSON using `geo2topo`. -* website/data/boundaries.geojson -* website/data/all_library_services.geojson - -The first is the "core" geojson file with boundaries for each library service. The only other data it holds is the name of each area. The second is the file created when we run `merge_service_data.py` to merge data from `website/data/library_services_information.csv` into `website/data/boundaries.topo.json`. - -These files aren't included in the GitHub repo for the simple reason that Git has a 100MB limit, and both files are larger than that. - -If you want to update library service data (e.g. to add missing data about the standard loan period for a particular library service) then **you should edit `website/data/library_services_information.csv`** — *not* `website/data/boundaries.topo.json`. After I merge your PR I will then pull down the updated file, run the merge script, and update the topoJSON file. It would be better to automate this and I can probably rewrite the script to update the TopoJSON directly, but currently that's the workflow, and it will *always* be that contributors should update the CSV file, not the JSON. \ No newline at end of file +This file isn't included in the GitHub repo for the simple reason that Git has a 100MB limit, and the file is larger than that. I could use Git-LFS but GitHub charges for moving large files around, and updating this file will rarely be necessary. If you want to access the geojson file you can find it at [librarymap.hugh.run/data/boundaries.geojson](https://librarymap.hugh.run/data/boundaries.geojson) \[105MB]. Contributors to this file are noted in [sources](sources.md). diff --git a/contributing.md b/contributing.md index e8d2290..ac27224 100644 --- a/contributing.md +++ b/contributing.md @@ -14,7 +14,9 @@ There is a class outline for an [introduction to Git and GitHub aimed at librari ### Which files to update -To update information about library *services* (e.g. fines info, loan period etc) you should edit `website/data/library_services_information.csv` +To update information about library *services* (e.g. fines info, loan period etc) you should edit `website/data/library_services_information.csv`. + +After your Pull Request is merged, a GitHub Action will automatically create a second pull request that merges data from `website/data/library_services_information.csv` into `website/data/boundaries.topo.json`. Please do not edit the `topo.json` file directly. To update information about library *locations* (e.g. street address, phone number, coordinates) you shoudl edit the relevant csv location file: @@ -23,8 +25,6 @@ To update information about library *locations* (e.g. street address, phone numb * `website/data/nsla_library_locations.csv` * `website/data/public_library_locations.csv` -Do not directly edit JSON files - these are [updated programatically](https://github.com/hughrun/public_library_map/blob/master/about.md#important-files-that-are-not-in-this-repository). - ### Citing and crediting data sources If you are adding a lot of data and have a new source for it, make sure it is cited. You should update the list of sources at both `sources.md` *and* `website/sources/index.html`. If your source is "I just know because it's my local library" or "I looked it up on their website" you don't need to add that to the list of sources. If your source is "I found a PDF listing every public library on the State Library website", you do. diff --git a/website/contributing/index.html b/website/contributing/index.html index 3c396cf..c8b7a9a 100644 --- a/website/contributing/index.html +++ b/website/contributing/index.html @@ -39,6 +39,7 @@

There is a class outline for an introduction to Git and GitHub aimed at librarians at librarycarpentry.org. This assumes you are using the command line. If you create or already have a GitHub account, you can also edit files directly in the browser, or use GitHub Desktop - both of which are probably less intimidating options if you don’t have any desire to learn how to use a command line/shell interface, or just want to make a single minor update.

Which files to update

To update information about library services (e.g. fines info, loan period etc) you should edit website/data/library_services_information.csv

+

After your Pull Request is merged, a GitHub Action will automatically create a second pull request that merges data from website/data/library_services_information.csv into website/data/boundaries.topo.json. Please do not edit the topo.json file directly.

To update information about library locations (e.g. street address, phone number, coordinates) you shoudl edit the relevant csv location file:

-

Do not directly edit JSON files - these are updated programatically.

Citing and crediting data sources

If you are adding a lot of data and have a new source for it, make sure it is cited. You should update the list of sources at both sources.md and website/sources/index.html. If your source is “I just know because it’s my local library” or “I looked it up on their website” you don’t need to add that to the list of sources. If your source is “I found a PDF listing every public library on the State Library website”, you do.

Missing or inaccurate data

-- 2.39.5