hugh/public_library_map
hugh/public_library_map
1
Fork 0
Code Issues 9 Pull requests Actions Packages Projects Releases Wiki Activity

Merge pull request #40 from hughrun/update-docs

Browse source 
update docs
This commit is contained in:
Hugh Rundle 2021-01-26 18:44:55 +11:00 committed by GitHub
parent a40bd76192 a36463cb3b
commit 6b35971d8e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 7 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
about.md
View file

@ -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. 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 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).
* 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.

6
contributing.md
View file

@ -14,7 +14,9 @@ There is a class outline for an [introduction to Git and GitHub aimed at librari
### Which files to 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` 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: 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/nsla_library_locations.csv`
* `website/data/public_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 ### 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. 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.

2
website/contributing/index.html
View file

@ -39,6 +39,7 @@
<p>There is a class outline for an <a href="https://librarycarpentry.org/lc-git/">introduction to Git and GitHub aimed at librarians</a> at <code>librarycarpentry.org</code>. This assumes you are using the command line. If you create or already have a GitHub account, you can also <a href="https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository">edit files directly in the browser</a>, or use <a href="https://desktop.github.com/">GitHub Desktop</a> - 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.</p> <p>There is a class outline for an <a href="https://librarycarpentry.org/lc-git/">introduction to Git and GitHub aimed at librarians</a> at <code>librarycarpentry.org</code>. This assumes you are using the command line. If you create or already have a GitHub account, you can also <a href="https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository">edit files directly in the browser</a>, or use <a href="https://desktop.github.com/">GitHub Desktop</a> - 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.</p>
<h3 id="which-files-to-update">Which files to update</h3> <h3 id="which-files-to-update">Which files to update</h3>
<p>To update information about library <em>services</em> (e.g. fines info, loan period etc) you should edit <code>website/data/library_services_information.csv</code></p> <p>To update information about library <em>services</em> (e.g. fines info, loan period etc) you should edit <code>website/data/library_services_information.csv</code></p>
<p>After your Pull Request is merged, a GitHub Action will automatically create a second pull request that merges data from <code>website/data/library_services_information.csv</code> into <code>website/data/boundaries.topo.json</code>. Please do not edit the <code>topo.json</code> file directly.</p>
<p>To update information about library <em>locations</em> (e.g. street address, phone number, coordinates) you shoudl edit the relevant csv location file:</p> <p>To update information about library <em>locations</em> (e.g. street address, phone number, coordinates) you shoudl edit the relevant csv location file:</p>
<ul> <ul>
<li><code>website/data/indigenous_knowledge_centre_locations.csv</code></li> <li><code>website/data/indigenous_knowledge_centre_locations.csv</code></li>
@ -46,7 +47,6 @@
<li><code>website/data/nsla_library_locations.csv</code></li> <li><code>website/data/nsla_library_locations.csv</code></li>
<li><code>website/data/public_library_locations.csv</code></li> <li><code>website/data/public_library_locations.csv</code></li>
</ul> </ul>
<p>Do not directly edit JSON files - these are <a href="https://github.com/hughrun/public_library_map/blob/master/about.md#important-files-that-are-not-in-this-repository">updated programatically</a>.</p>
<h3 id="citing-and-crediting-data-sources">Citing and crediting data sources</h3> <h3 id="citing-and-crediting-data-sources">Citing and crediting data sources</h3>
<p>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 <code>sources.md</code> <em>and</em> <code>website/sources/index.html</code>. 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.</p> <p>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 <code>sources.md</code> <em>and</em> <code>website/sources/index.html</code>. 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.</p>
<h3 id="missing-or-inaccurate-data">Missing or inaccurate data</h3> <h3 id="missing-or-inaccurate-data">Missing or inaccurate data</h3>