Georeferencing and Displaying Historical Maps using Map Warper and StoryMap JS

sferna109 commented 3 years ago

The Programming Historian has received the following tutorial on 'Georeferencing and Displaying Historical Maps using Map Warper and StoryMap JS' by @ericayhayes. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/en/drafts/originals/displaying-georeferenced-map-knightlab-storymap-js

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me.

Our dedicated Ombudsperson is (Ian Milligan - http://programminghistorian.org/en/project-team). Please feel free to contact him at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudsperson will have no impact on the outcome of any peer review.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. Thank you for helping us to create a safe space.

[Permission to Publish]

The editor must also ensure that the author or translator post the following statement to the Submission ticket.

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a CC-BY license.

mariajoafana commented 3 years ago

Hi, just a quick note to point out that we have an Introduction to Map Warper tutorial available in Spanish. Please make sure that this tutorial complements the tutorial that we already have and to what extent it overlaps on the MapWarper part. This might be a good opportunity to start translating Spanish language tutorials into English!

svmelton commented 3 years ago

Hi @sferna109—just checking in to see how this lesson is progressing. Do you need any help?

sferna109 commented 3 years ago

Hi @sferna109—just checking in to see how this lesson is progressing. Do you need any help?

Hi @svmelton, my apologies I have been a little bit confuse with the process and I have not had the change to continue working with this lesson review. Could you assist me to proceed or could someone else take this lesson? Appreciate if this is possible.

svmelton commented 3 years ago

Hi @sferna109: just sent you a message to set something up to walk through any questions!

svmelton commented 3 years ago

Hi @ericayhayes! Just letting you know that @hawc2 will be taking over as editor for this piece. He'll be providing initial feedback and finding initial reviewers.

anisa-hawes commented 3 years ago

Hello @ericayhayes. My name is Anisa, and I'm going to be shadowing @hawc2 as he edits this lesson. I'm a new member of the Programming Historian team, and I'm keen to learn more about our editorial processes. Please let me know if you have questions, or if there are any specific challenges I can help support along the way.

ericayhayes commented 3 years ago

Great, thank you! It has been a long time since Mia Partlow and I submitted this lesson. Please let us know what the next steps are. Thanks, Erica

anisa-hawes commented 3 years ago

Thank you for your patience, @ericayhayes. The next step is that the newly assigned editor Alex (@hawc2) will read through your submission in full. He'll post comments and any suggested revisions here, within the Conversation thread. He will work with you and Mia to shape the lesson so that it is ready for Open Peer Review.

Then, Alex will identify and contact two peer reviewers, who will join our dialogue here in the thread to offer you their feedback and ideas. After that, Alex will support you to make any necessary revisions and think about how to integrate what has been learned during review. The final steps are copyediting, then the Managing Editor's (@svmelton) final checks before publication.

ericayhayes commented 3 years ago

Sounds good. Thanks.

anisa-hawes commented 3 years ago

No problem. I'm sorry there has been a delay due to the change of editor. Alex and I are both looking forward to working with you on this.

hawc2 commented 3 years ago

@ericayhayes apologies for delays on moving this forward - I've cleaned up the lesson so images appear in the lesson preview linked at the start of the issue. The lesson looks generally good to me, so to keep things moving I'm going to save any minor revisions I have for after we hear back from peer review. I'll send this out and hopefully we will get feedback later this fall.

ericayhayes commented 3 years ago

Great, thank you! @mapartlo and I are looking forward to getting feedback. Just tagging her in this post, so she can stay in the loop on our submission.

hawc2 commented 3 years ago

@ericayhayes and @mapartlo, @erslayton and @lgauthereau will be reviewing this lesson. Hopefully we will get you feedback in the next month or so. After they both post their reviews, I'll provide some synthesizing commentary and give you @ericayhayes directions for revision

ericayhayes commented 3 years ago

Sounds good. Thanks!

lgauthereau commented 2 years ago

@ericayhayes and @mapartlo, this tutorial is very useful and easy to follow. I have a few minor suggestions, but as a whole felt that it was solid.

Since we decided to cut the tutorial in two, you do need to add an introduction about StoryMap JS (What it is, who created it, what types of map visualizations it makes, and that you can import custom maps). You should also remove the references to the Map Warper North Carolina example, but I do think you can make a reference that suggests you can import from Map Warper and list other possible sources for import.

[x] Introduction: Add an introduction to StoryMap JS.
[x] Step 1.1: Change the wording : Go to StoryMap JS and select “Make a Map.” to: Go to the StoryMap JS website and click on the green button that says “Make a StoryMap.”
[x] Step 2: Change “You will want to change out this basemap layer with your georeferenced historical map of North Carolina. To change the default basemap layer, select Options in the top left hand corner of the Story Map JS interface.” to “To change the default basemap layer to your georeferenced historical map, select Options in the top left hand corner of the Story Map JS interface.
[x] Since this is no longer part of the tutorial that uses the North Carolina map, remove references to North Carolina. Instead, you can suggest that the user type in the name of one of the cities that they georeferenced in their custom map.
[x] Check steps numbering. There are two 1s under Step 3.
[x] Mention that user can add descriptive text under the Headline.
[x] At end: suggest people go to Preview tab to see the StoryMap slides.
[x] Tell users to click the Save button in the upper lefthand corner.
[x] Mention if it is published as soon as you click Save. Clarify how to share the map once it’s published.
[x] Conclusion: Revise to reflect only StoryMap JS section.

ERSlayton commented 2 years ago

@ericayhayes and @mapartlo thank you for sharing this with me. Overall a great read. I found the details elucidating and can see a beginner learning well from the guide. I appreciated the amount of visual aids that show the process! They are very helpful.

There are times where more detail could be provided, but I understand that there are some constraints with the length of the lesson.

[ ] You might consider adding similar language to explain georeferencing or GIS as you did in the Georeferencing and QGIS module. For example, the language used in the other lesson explains the techniques for using control points to fit with 2d objects, which I think is helpful to have described here as well as not everyone will click out to wiki or the other lesson.
[ ] Might provide more descriptions in the caption under the map. It may be obvious, but what led to that warping, describe it below the image as well as describing the map. It might help provide context to the reader.
[ ] As you get started with the map warper section you jump straight into the install. Might be helpful to discuss broader use of the tool and an about section? Show readers the wide operability of tools
[ ] Perhaps when telling people to sign up for the map wrapper account link to that page and not the general page?
[ ] You might consider adding some advice about what metadata is important, or directly have it represented in the text. Again, people might not click out to the link, and it is something they should learn as a part of this lesson.
[ ] Is there a way to have in text the names of buttons or clickable links on other pages highlighted or font changed so they stand out from the rest of the text. This might help with readability. Might also help to copy an image of the icons you mean (green map icon for example) as a guide.
[ ] I do wonder, for listing out major cities as a point for control, is it possible to know that the georeferenced center of the city, where the digital map will be, is going to be the same point as referenced in the historic map? Is this worth mentioning as introducing fuzzy data? I leave that up to you.
[x] Again, in the storymaps.js section, it might be a good idea to include more descriptive captions of the objects or process depicted along with the image, as a touch point for the reader
[ ] In the conclusion you might provide an example of a classroom application to give instructor an idea about how to integrate this lesson into their teaching.

ericayhayes commented 2 years ago

Per @hawc2 and @lgauthereau feedback via email and Zoom conversation, @mapartlo and I have submitted the new version of this lesson at the following pull request: https://github.com/programminghistorian/ph-submissions/pull/450

Emma's comments differed from Lorena's which focused more on changing the current lesson submission, which focused more heavily on georeferencing historical maps in Map Warper.

hawc2 commented 2 years ago

@ERSlayton @lgauthereau Could you take one last look-over at this lesson and let me know if you see any lingering issues? I can then provide any final feedback and we should be good to go. @lgauthereau if you do have a draft of the translation available for us to review soon, I can take that into consideration when I give @ericayhayes feedback.

ericayhayes commented 2 years ago

I was able to push the changes directly to the repo after receiving your write permissions invitation. All changes should now be there. I closed the pull request.

lgauthereau commented 2 years ago

I think the revisions look great. The intro provides a good overview of the tool and the lesson's objectives and the lesson itself is clear and easy to follow.

ERSlayton commented 2 years ago

It looks good to me.

hawc2 commented 2 years ago

Thanks @lgauthereau and @ERSlayton for reviewing this lesson and helping guide @ericayhayes and @mapartlo as they revised and made sure to not overlap with the Spanish Map Warper lesson. @ericayhayes and @mapartlo you did a great job of redesigning this lesson to focus entirely on Storymaps.

I'm looking forward to seeing you and @lgauthereau submit the translation of the Map Warper lesson so readers could look at both these lessons together for #426. Make sure to consider @ERSlayton's feedback here on the Map Warper section in case anything applies.

This lesson is now ready for copyediting @svmelton and @anisa-hawes. Note that the title has now changed to “Displaying a Georeferenced Map in Storymap JS”. I have updated the original issue with this info. I’ve also input all the yaml information necessary by this point such as abstract and difficulty info.

Here’s the directory info:

images/displaying-a-georeferenced-map-in-storymap-js/ - images files lessons/displaying-a-georeferenced-map-in-storymap-js.md - the lesson file gallery/displaying-a-georeferenced-map-in-storymap-js.png - the modified avatar gallery/originals/displaying-a-georeferenced-map-in-storymap-js-original.png - the original avatar

And bios:

- name: Erica Y. Hayes
  team: false
  orcid: 0000-0001-8601-9834
  bio:
      en: |
          Erica Y. Hayes is a Digital Scholarship Librarian at Villanova University.

- name: Mia Partlow
  team: false
  orcid: 0000-0002-9329-281X
  bio:
      en: |
          Mia Partlow is a Resource Sharing Librarian at NC State University.

anisa-hawes commented 2 years ago

Thank you, @hawc2!

I'll post a comment here when my suggestions are ready for your review @ericayhayes and @mapartlo.

anisa-hawes commented 2 years ago

Hello @ericayhayes and @mapartlo,

I’ve copyedited your lesson, and my suggested revisions are now ready for your review.

I've applied my suggested revisions directly to the markdown file in our Submissions Repository. You can view the individual additions and subtractions I’ve made here in the Commit History.

I’m going to paste a list of my comments and suggested revisions below too, so that the copyediting process is transparent.

[x] para.37 I've replaced ‘this information’ with ‘the following information’ and I've added a colon:
[x] para.48 I've added links to KML, Web Map Services (WMS), and Tiles
[x] l.66 I've capitalised Google
[x] para.74 I've added colon:
[x] para.79 I've adjusted 'The plus Add Slide icon allows you ‘ to ‘The plus icon labelled “Add Slide” allows you’
[x] para.80 I've adjusted ‘The Media section of your slide allows you to upload images or link to images, video streaming services (e.g., YouTube, Vimeo, SoundCloud, etc.).’ to ‘The Media section allows you to upload images or link to images, video streaming services (e.g., YouTube, Vimeo, SoundCloud, etc.) to your slide .’
[x] para.81 I've added "</>",
[x] para.81 I've capitalised Background Options and Marker Options
[x] para.84 I've adjusted 'At the top of the StoryMap JS authoring tool interface, you will see an options dialog box in the left-hand corner’ to ‘At the top left-hand corner of the StoryMap JS authoring tool interface, you will see an Options button’
[x] para.102 I've deleted an extra ‘the’
[x] para.116 I've added alert info box* around ‘Note’
[x] para.120 I've adjusted ‘at a website like’ to ‘from a website such as’
[x] para.122 I've added a closing bracket
[x] para.126 I've added an alert info box* around ‘Note’
[x] para.138 I've adjusted ‘You should use an image with the appropriate permissions.’ to ‘You should use images and media with the appropriate permissions.’
[x] para.164 I've adjusted ’Marker Options button in the bottom right corner’ to ‘Marker Options button at the bottom right corner’
[x] para,164 I've adjusted ’in an image search tool’ to ’using an image search tool.’

*N.B. 1. Alert info boxes are formatted in html and don't show up on GitHub's in-built preview. They will show on the site!

I noticed that you'd formatted the Note text in italic, and I don't think this is necessary if we have the boxes. What are your thoughts @hawc2?

Let me know if you're happy with these adjustments. My next step will be to replace all external links in the lesson with sustainable perma.cc links.

Hello @hawc2,

I've made a couple of small adjustments to the YAML header:

[x] removed translation_date:
[x] removed translator:
[x] removed translation-editor:
[x] removed translation-reviewer:
[x] added square brackets around [mapping]
[ ] added avatar_alt: field *this is for you to fill in
[ ] added doi: field *this is for Sarah to fill in later

anisa-hawes commented 2 years ago

Hello all,

Please note that this lesson's .md file has been moved to a new location within our Submissions Repository. It is now found here: https://github.com/programminghistorian/ph-submissions/tree/gh-pages/en/drafts/originals

A consequence is that this lesson's preview link has changed. It is now: http://programminghistorian.github.io/ph-submissions/en/drafts/originals/displaying-a-georeferenced-map-in-storymap-js

Please let me know if you encounter any difficulties or have any questions.

Very best, Anisa

anisa-hawes commented 2 years ago

Hello @hawc2, @ericayhayes, @mapartlo,

I've gone ahead and carried out the following tasks:

[x] Replaced external links with Perma.cc archival links, except para.62 and para.66 which direct to actions on the live web
[x] Removed italics within alert-info boxed, para. 117 and para. 127
[x] I've also adjusted internal links to PH lessons in para.33, so that these are "relative links"

Please let me know if you'd like to discuss any of the copyedits I've suggested above.

All best, Anisa

hawc2 commented 2 years ago

Thanks @anisa-hawes! @ericayhayes @mapartlo are you fine with these changes? Let us know if there's anything you're not sure about. Once this stage is complete, we can move on to publishing the lesson

hawc2 commented 2 years ago

@ericayhayes and@mapartlo can you also post a message to this issue with the following text adapted to your agreement: "I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a CC-BY license."

mapartlo commented 2 years ago

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a CC-BY license.

ericayhayes commented 2 years ago

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a CC-BY license.

hawc2 commented 2 years ago

@svmelton this lesson should be ready for publication!

en/drafts/originals/displaying-georeferenced-map-knightlab-storymap-js.md - the lesson file images/displaying-georeferenced-map-knightlab-storymap-js/ - images files gallery/displaying-georeferenced-map-knightlab-storymap-js.png - the modified avatar gallery/originals/displaying-georeferenced-map-knightlab-storymap-js-original.png - the original avatar

Note, the lesson is now previewable at this link: https://programminghistorian.github.io/ph-submissions/en/drafts/originals/displaying-georeferenced-map-knightlab-storymap-js

hawc2 commented 2 years ago

I also wanted to note, after @mariajoafana pointed out there was already a Spanish lesson on Map Warper, the authors @ericayhayes @mapartlo edited the original to make this separate lesson on Knightlab Storymaps.

They've also co-translated into English with @lgauthereau the original Spanish Map Warper lesson. See #426, now at the review stage. The translated English lesson draft is viewable at the following link:

https://programminghistorian.github.io/ph-submissions/en/drafts/translations/introduction-map-warper

svmelton commented 2 years ago

Excellent! I've requested a DOI and will move forward with the final publication process once we have it.

svmelton commented 2 years ago

We're live! http://programminghistorian.org/en/lessons/displaying-georeferenced-map-knightlab-storymap-js

Thanks to everyone for your hard work on this, glad to see it published!

programminghistorian / ph-submissions

Georeferencing and Displaying Historical Maps using Map Warper and StoryMap JS #349

Anti-Harassment Policy