programminghistorian / ph-submissions

The repository and website hosting the peer review process for new Programming Historian lessons
http://programminghistorian.github.io/ph-submissions
138 stars 113 forks source link

Translation of Introducción a Map Warper #426

Closed hawc2 closed 1 year ago

hawc2 commented 2 years ago

The Programming Historian has received a proposal to translate "Introducción a Map Warper" into English. The translation will be authored by @lgauthereau @ericayhayes and @mapartlo.

This translation has been developed out of an original proposal by @ericayhayes and @mapartlo entitled "Georeferencing and Displaying Historical Maps using Map Warper and StoryMap JS" (issue #349). As noted in that ticket, their proposal overlaps with the previously published Spanish lesson introducing Map Warper. To avoid overlap, @ericayhayes and @mapartlo will revise their original English lesson to focus on building off the Spanish lesson to focus on Storymap JS and other extensions of Mapwarper.

In parallel, this translation of the Spanish Mapwarper lesson into English will ensure both lessons can be linked in English and build off one another. Subsequent to the publishing of the original English lesson on StoryMap JS, it will also be translated into Spanish (by @lgauthereau or another translator we find). In this way, both English and Spanish journals will have published a two-part lesson on MapWarper and StoryMap JS.

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.

hawc2 commented 2 years ago

The lesson files and images have now been uploaded, and the lesson is previewable at the following link.

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

Let me know if you see any small changes I should make. I'll review the lesson once and will follow up with you shortly.

lgauthereau commented 2 years ago

NB: This is a liberal translation, not a word-for-word translation, as it was first submitted as a lesson in English. I tried to include as much as possible from the English submission and integrate it into the translation. We swapped out the example to include a map in English, but the original map is cited in a note in the translation.

ericayhayes commented 2 years ago

Please note this is a liberal translation and is not an exact word-for-word translation. Some of the differences include:

-A USA North Carolina map example rather than a Map of the Republic of Colombia -More notes and explanations (e.g., the RMS error code section) -A note about displaying the map online with a link to the Displaying A Georeferencing Map in StoryMap JS lesson

hawc2 commented 2 years ago

This lesson looks good to go out for review. Thanks to the authors for help fixing some markdown issues. I'll follow up once we've identified two reviewers.

hawc2 commented 2 years ago

I'm happy to report @JoshuaGOB and @aycasarez have agreed to be reviewers of this translated lesson. Let's aim to get both reviews in by mid-June.

Please post your feedback here, general and specific line edits. Using Markdown checkboxes can make the minor edits easier for the authors.

In this case, keep an eye out for differences between the original and the new translation, and we can discuss here which differences make sense for the translated version.

Thanks all!

aycasarez commented 2 years ago

Hi everyone! I fell a little behind on this, but I am working on reviewing the lesson now. I will have the review finished by Friday at the latest. Thanks for your patience and talk soon!

aycasarez commented 2 years ago

Apologies for the delay. Here is my review of the translated lesson. These are just suggestions and I am happy to discuss or clarify any of my comments! Thank you @lgauthereau and @ericayhayes for your excellent work in translating and adapting this lesson. I have often shied away from spatial humanities, but I found this really approachable and dare I say- fun?

To start off, I really appreciate the addition of georeferencing definition in the translated version.

Para 7 - Is there clearer way to indicate how to download the jpg version of the map? Or another way to provide the jpg? This might just be user error on my part, but I had some trouble finding a jpg to download on the David Ramsey site. The download links under the Media Information only seem to provide JP2 and SID files. I right clicked and saved as on the map to download a png, which is the file that I used in the tutorial.

Para 13- historical maps instead of antique maps?

Para 18 - Source: url for the document source [I think that is what we're trying to refer to]

Para 25 - Layer icon link broken -New line for the Add custom basemap feature explanation

Para 33 - This table also includes a section that defines the geometric error value, caused by the georeferencing of the historic map document

Para 38 - is it possible to create a frame around this box like used in the original?

Para 39 - Fantastic walkthrough! Could you title it with something that distinguishes it from the explanatory interface section above? Perhaps a title like “Practice” or “Activity”? Also, I appreciate the note on the error value and what it means.

Para 48 - display window? or display box? as a translation for “recuadro de visualización”

Para 51 - Title suggestion - “Preview” instead of “Previsualization"

Para 53 - ellipsoid

Para 56 - "Any MapWarper user can monitor the changes to the map” in place of 'All users can monitor the change to the map. “

JoshuaGOB commented 2 years ago

Congratulations to @lgauthereau, @ericayhayes, and @mapartlo for their fantastic work. It complements and improves on the original lesson while still making it approachable and easy to follow. Kudos!

Being familiar with the original, I have to admit that I was even more impressed by the translation. I only have a few suggestions to add to the fantastic work by @aycasarez and I'll try to not repeat myself except to offer additional phrasing or emphasizing key comments.

154 - Could also read: This table also includes a section that defines the geometric error value, caused by the georeferencing the historic map document

Thank you for the opportunity to review the lesson and congratulations on doing such good work!

hawc2 commented 2 years ago

Thank you @JoshuaGOB and @aycasarez! Sounds like this lesson is in really solid shape, and all the feedback is clearcut.

@lgauthereau @ericayhayes @mapartlo can you make these revisions soon? I can read through it and give a last round of feedback, and @anisa-hawes will also give it a final round of copy-edits. Hopefully we can publish this pretty quickly!

lgauthereau commented 2 years ago

Thanks all! @ericayhayes and @mapartlo I'll send you an email so we can plan out the revisions.

ericayhayes commented 2 years ago

@hawc2, we went through the revisions and I went ahead and pushed those changes to GitHub. Let us know if there is anything else you need from us.

hawc2 commented 2 years ago

Looks good to go for copy-editing @anisa-hawes!

hawc2 commented 2 years ago

@lgauthereau while we wait on copyedits, can you post this statement to this 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](https://creativecommons.org/licenses/by/4.0/deed.en) license.

There's also some other metadata we'll need for the lesson. Take a look at the markdown on the original Spanish lesson to translate it from there:

difficulty: TBC
activity: [TBC]
topics: [TBC]
abstract: TBC
avatar_alt: TBD
lgauthereau commented 2 years ago

I the 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.

lgauthereau commented 2 years ago

Hi @hawc2 I'm only seeing difficulty in the original metadata. Is there a guide with specific vocabulary for activity/topics? And do we determine the avatar_alt?

difficulty: Medium activity: [TBC] topics: mapping abstract: This lesson will guide users through uploading a scanned map and georeferencing against OpenStreetMap using Map Warper. avatar_alt: TBD

hawc2 commented 2 years ago

No worries, I can update the rest of that and I'll ping you if I have questions. Still figuring out how some of this works for translations. Once Anisa finished copy-edits on this lesson, I'll move it into publication. Thanks all!

On Mon, 8 Aug 2022 at 11:41, Lorena Gauthereau @.***> wrote:

Hi @hawc2 https://github.com/hawc2 I'm only seeing difficulty in the original metadata. Is there a guide with specific vocabulary for activity/topics? And do we determine the avatar_alt?

difficulty: Medium activity: [TBC] topics: mapping abstract: This lesson will guide users through uploading a scanned map and georeferencing against OpenStreetMap using Map Warper. avatar_alt: TBD

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1208291538, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4ED73HZFDLPL3ERNGEDVYETBRANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

--

Alex Wermer-Colan, PhD

Temple University, Scholars Studio

anisa-hawes commented 2 years ago

Dear @lgauthereau, @ericayhayes, @mapartlo + @hawc2.

I've applied the copyedits + perma.cc links to your translation. Please let me know if you're happy with the adjustments. See Update introduction-map-warper.md.

I do have a couple of small questions: (N.B. Line numbers below refer to the line numbers of the Markdown file here)

Last thing:

@hawc2, I've adjusted a couple of fields in the YAML and a couple are still to be completed:

Next steps:

Very best, Anisa

lgauthereau commented 2 years ago

Hi @anisa-hawes @hawc2 What is the suggested length of the abstract, per PH standards?

hawc2 commented 2 years ago

2-3 sentences is good, in this case it can be similar or the same as on the original spanish lesson

On Mon, 15 Aug 2022 at 09:56, Lorena Gauthereau @.***> wrote:

Hi @anisa-hawes https://github.com/anisa-hawes @hawc2 https://github.com/hawc2 What is the suggested length of the abstract, per PH standards?

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1215043079, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4EAQIX6GUEWW4QOIBYTVZJEBJANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

-- --- Alex Wermer-Colan, Ph.D. (he/him)

Administrative Lead, Philly Community Wireless

Managing Editor, Programming Historian in English Interim Academic Director, Temple University's Scholars Studio

anisa-hawes commented 2 years ago

Thank you @lgauthereau! I've received your Authorial-copyright-and-publishing-rights form 🙂

The original ES abstract is: En esta lección aprenderás a georreferenciar imágenes digitales con la herramienta Map Warper y a vincularlas a sistemas de información geográficos if you want to use or adapt this.

hawc2 commented 2 years ago

@lgauthereau @ericayhayes @mapartlo, as I go to publish this lesson, I'm noticing images for the buttons aren't rendering the same. @anisa-hawes this is actually because we switched to the liquid syntax. They used the ![]() syntax for images because that's what the original spanish used.

Did the other minor changes Anisa asked for get done? I'll aim to publish this very soon. We can always tweak the button images later if necessary, as this seems to stray from our usual formatting and may require some thinking about liquid syntax for this kind of bullet point

hawc2 commented 2 years ago

Actually @anisa-hawes I think the liquid syntax broke the gifs

lgauthereau commented 2 years ago

Hi all, I realized I had already translated the original abstract (which was only 1 sentence). But if we want something longer, I've added more below:

This lesson will guide users through uploading a scanned historical map and georeferencing against OpenStreetMap using Map Warper. Users will then export the georeferenced map as a WMS, Tiles, GeoTIFF, or KML file. This lesson can be used in conjunction with the Displaying a Georeferenced Maps in Story Map JS Programming Historian lesson.

hawc2 commented 2 years ago

thanks @lgauthereau. once I hear back from @anisa-hawes and we fix some minor rendering issues, we'll publish the lesson

anisa-hawes commented 2 years ago

Actually @anisa-hawes I think the liquid syntax broke the gifs

Hello @hawc2. Oh, this is strange. As I explained above, I did notice that the tiny icon images no longer displayed 'inline' with the text when I added in the liquid syntax, but I don't think this is what has broken the .gifs. Also, I note also that the Create an Account .gif in the Getting Started section (l.75 of the Markdown) still works as it should... (Is it because there are no captions caption=?) Anyway, if we want to keep the icons, and display them inline, I think we would need to add the ![text](link) formatting back in.

I know that liquid syntax can work with .gifs because I checked the code for an ES lesson that I remembered includes them too: Análisis de corpus con Voyant Tools. The Markdown for that lesson is here.

--

Reviewing my comment above and double checking the recent commit history, it looks like we are still waiting for the other small changes/responses to those suggestions. Let us know if you have time to check in, @lgauthereau / @ericayhayes / @mapartlo?

hawc2 commented 2 years ago

@ericayhayes was helping before with a bunch of the formatting and liquid syntax stuff. Erica, would you be available to help with making some of these final changes to the lesson? I'm agnostic about using Liquid or simpler syntax, so I'll leave it up to the authors in this case as long as it renders right.

mapartlo commented 2 years ago

Erica and I are taking a look at this next week, it may not be until next Friday that we're able to dive in.

On Thu, Sep 1, 2022 at 9:11 PM Alex Wermer-Colan @.***> wrote:

@ericayhayes https://github.com/ericayhayes was helping before with a bunch of the formatting and liquid syntax stuff. Erica, would you be available to help with making some of these final changes to the lesson? I'm agnostic about using Liquid or simpler syntax, so I'll leave it up to the authors in this case as long as it renders right.

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1234957313, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHST52TDSGZ7PHEJPLVLILTV4FH53ANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

ericayhayes commented 2 years ago

@hawc2 @mapartlo and I met last Friday to go over Anisa's comments. We tried to figure out how to display the tiny icon images 'inline' with the text in liquid syntax, but none of my edits worked. The only way I was able to display them inline without using markdown was using html code directly in the file. For example, img src="/ph-submissions/images/introduction-map-warper/add_control_point.gif" alt="Add Control Point icon" works. See line 122 or paragraph 25 as an example. I didn't want to go through and change all of the liquid syntax to html if it is unacceptable to you and the editors. Please let me know. @mapartlo and I are meeting again this Friday to go through the rest of Anisa's comments and I can update those changes if that's okay with you. Thanks!

hawc2 commented 2 years ago

that sounds great, thanks!

I'll defer to Anisa about finalizing the code for rendering gifs, but I guess I thought the first option, used in the original Spanish lesson, was the simplest?

On Tue, Sep 13, 2022, 11:48 AM Erica Y. Hayes @.***> wrote:

@hawc2 https://github.com/hawc2 @mapartlo https://github.com/mapartlo and I met last Friday to go over Anisa's comments. We tried to figure out how to display the tiny icon images 'inline' with the text in liquid syntax, but none of my edits worked. The only way I was able to display them inline without using markdown was using html code directly in the file. For example, [image: Add Control Point icon] http:///ph-submissions/images/introduction-map-warper/add_control_point.gif works. See line 122 or paragraph 25 as an example. I didn't want to go through and change all of the liquid syntax to html if it is unacceptable to you and the editors. Please let me know. @mapartlo https://github.com/mapartlo and I are meeting again this Friday to go through the rest of Anisa's comments and I can update those changes if that's okay with you. Thanks!

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1245604189, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4EERGR5BN7VHHOGNOT3V6CO37ANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

ericayhayes commented 2 years ago

@anisa-hawes see @hawc2 comment above. Could you let us know what code to use for displaying the gifs inline?

hawc2 commented 2 years ago

@anisa-hawes lmk if I can help with finalizing this lesson, we've just got a couple tweaks to make before publishing

mapartlo commented 2 years ago

@ericayhayes and I investigated how to display the images and gifs inline. It looks like liquid syntax does not support this, so we need to rewrite the image code. Erica and I have been discussing, but we welcome any help.

anisa-hawes commented 2 years ago

Hello @hawc2, @ericayhayes and @mapartlo. Apologies for the delay. I've taken out the liquid syntax and have reintroduced the Markdown to display the .gifs inline.

N.B. Alex, when we move the files over, I will need to adjust the links so that they point to the .gifs on Jekyll (relative links) rather than on submissions i.e., </images/filename.gif> instead of < http://programminghistorian.github.io/ph-submissions/images/filename.gif >

anisa-hawes commented 2 years ago

Hello @ericayhayes, @mapartlo,

Just to draw your attention to a couple of outstanding questions from my comment above:

Next steps @hawc2:

ericayhayes commented 2 years ago

Hi @anisa-hawes,

To answer your questions:

If you click on the link, it will appear as a small tile image because like the above question, it is a Map Tile export URL, not a website. We put this URL in a code block for this reason.

Let us know if we need to make any changes.

anisa-hawes commented 2 years ago

Thank you for the explanation, @ericayhayes. That approach to the map tile links makes sense.

I wonder if @rivaquiroga knows what the World Map tool referred to in paragraph 2 of the original ES lesson is? Is it still active?

If not, I think we should take this reference out. It isn't useful if it isn't identifiable. And it cannot be found through an online search because the name is too general.

anisa-hawes commented 2 years ago

Hello @hawc2

Other than this final query, the lesson is ready for your final read-through.

I've already received and uploaded the translators' copyright declaration forms.

There are a couple of YAML fields for you to complete when you move the files over too:

rivaquiroga commented 2 years ago

I wonder if @rivaquiroga knows what the World Map tool referred to in paragraph 2 of the original ES lesson is? Is it still active?

I believe it might be this one: https://worldmap.maps.arcgis.com/home/index.html

anisa-hawes commented 2 years ago

Thank you, @rivaquiroga!

@ericayhayes, I've updated the lesson to add in this link. (Please note that it hasn't been possible to create a perma.cc link in this case – I think the problem is that WorldMap's home page immediately launches a pop-up upon opening).

I've also updated the abstract. Upon re-reading I felt it could benefit from some more detail and could be clarified. Please let me know if you want to adjust this, or if you're happy with the changes. abstract: "This lesson introduces basic use of Map Warper for historical maps. It guides you from upload to export, demonstrating methods for georeferencing and producing visualizations."

lgauthereau commented 2 years ago

@anisa-hawes I think the revised abstract sounds accurate. Thanks!

ericayhayes commented 2 years ago

@anisa-hawes, Same. I think the revised abstract sounds good. Thanks!

hawc2 commented 2 years ago

hey all, I was hoping to say we could move forward with publication, but strangely enough, the images for this lesson aren't displaying normally on the preview now.

It took me a few to figure it out, but it must be due to @anisa-hawes adding the yaml line identifying the "original: introduccion-map-warper", which now leads the ph-submissions repo to look for the images in the Spanish image directory, as documented in this issue #2578 "Images not displaying on ph-submissions" (https://github.com/programminghistorian/jekyll/issues/2578) identified by @jenniferisasi.

Will this problem replicate on the Jekyll site, or is it only a preview problem with the ph-submissions repo @ZoeLeBlanc? Do we need to move all the image files to the Spanish language directory now, or is there another solution in how we edit the .yaml file?

Thanks to the authors for their patience as we figure this out - alot of these problems we're encountering relate to publishing PH tutorials in translation into English. We're trying to improve our docs and technical process for doing this as we work on this lesson. The cool thing is, and partially as an explanation for these bugs, as far as I understand this Map Warper translation will be the very first translation of a Programming Historian lesson into English from another language!

hawc2 commented 2 years ago

I've started drafting the final published version in our main site, and I created a pull request #2711 where we'll work out the remaining issues with the images rendering. I'll ping the authors if we need you to look it over. Almost there!

hawc2 commented 1 year ago

@lgauthereau @ericayhayes @mapartlo congratulations, your translation, "Introduction to Map Warper" is now published!:

https://programminghistorian.org/en/lessons/introduction-map-warper

This was the first translation into English of a lesson originally published in another language! So a cause for celebration and hopefully the first of many more.

Big thanks to @JoshuaGOB and @aycasarez for your thorough reviews!

And thanks everyone for your help with elements of this lesson, especially @anisa-hawes @rivaquiroga @jenniferisasi @svmelton!