Language Independence

[ianmilligan1]

I wanted to move the conversation from #647 so policy discussions don't get wrapped up with an individual lesson.

@arojascastro noted below:

I may be wrong but the point is that Geoparser only recognizes named entities in English; I have never used it but I checked the website and I did not see any way to change the language parameter or whatever. So if anyone translates this lesson, s/he will have to use the text in English - because it will not work with texts in Spanish.

What do you think? @vgayolrs @mariajoafana

On the other hand, maybe it would be good pracrice to accept the publication of lessons that takes into consideration how dependant the content is on language.

Examples:

• is it possible to use texts in different language other than English? Then it may be accepted
• can you use resources that are transnational (for instance Europeana)? Fine!
• are you using tools that are available in different languages? Perfect!

In my opinion, if the PH is committed to open access and free tecnologies, it may be good idea to extend its committment to multilingual tecnologies as well... of course a first step could be tecnologies that are localisation friendly...

[ianmilligan1]

My own two cents is that I think it's worth making a consideration, but I don't think we want to have yet another blanket policy.

The Geoparser is a good example: by default it focuses on English, but a research team could tweak different elements to make it work in different languages. It would take effort and time, and it's not realistically feasible for tool projects to implement all of this out of the box on the resources that most DH projects have.

For what it's worth, my work for example focuses on English-language tools out of the box, mostly because (a) that's our expertise; (b) our pipeline of tools; and (c) our local users. We make it so that it's extendable down the road for other linguistic communities, but in some cases that's going to require people to do a bit of their own legwork on the text classifier front. With these complex tools, language independence isn't something you're going to easily have out of the box, especially given interdependent processing steps.

[arojascastro]

Yup, I agree mostly, I think you could take into account when reviewing proposals - just as one factor amongst others.

However, your scenario applies well to programming languages, tools and methods mostly.

What about the reuse of information already published by third parties? I think a great amount of work can be on this second direction: to use resources that are transnational and multilingual. They already exist. So for instance, instead of mining the Internet Archive, why not mining Europeana?

At the moment all PH contents, examples and resources are focused on the English culture, which of course makes total sense because authors are English or American, but the audience... is it English or American only?

I do not think it would take a lot of effort to look for examples and resources that are not that dependent on language -- that are more diverse. We cannot limit diversity to the composition of our team board... it must be reflected on content as well. I insist this is feasible for all authors.

[acrymble]

It could be something that someone mentions at the review stage if a lesson looks like it will be heavily focused on English material. Maybe someone with experience translating could just say something like: 'is there a way this could be altered so that we could more easily translate it into Spanish and other languages?'

[mdlincoln]

@arojascastro Does this guideline need to be written down in our editorial and/or reviewer guidelines?

[arojascastro]

In my opinion, yes. But maybe we should vote? Or see more views? It is up to you (English team) really.

[mdlincoln]

I think it makes sense as a guideline - something that editors and reviewers should keep in mind, much like they do all the other traits of lessons that we try to cultivate. @arojascastro would you like to draft some additions to those pages and submit it as a PR? Then we can all take a look at those.

[arojascastro]

Yes, @mdlincoln I'll take this. I need some days, but I am back on tracks and working for the PHes fully (I had to focus on teaching).

[arojascastro]

I found these resources by the W3C about internationalization and localization: https://www.w3.org/International/getting-started/index

After reading, I drafted this text. Of course, my English can be improved, do not hesitate to suggest improvements concerning language and contents.

Internationalization and localization

As the World Wide Consortium (W3C) reminds us, internationalization "is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language". Since 2017 The Programming Historian has become an international and multilingual website that provides lessons for English and Spanish audiences (February 2018). For this reason, we encourage authors to adopt an international outlook while writing their lessons. Key aspects to be considered include but are not limited to:

• Images, texts and datasets should be as cosmopolitan as possible accordingly with our global audience. We recommend using international resources well known all around the world.
• Examples, representations, icons, symbols and colors are important. We encourage seeking cases that embrace diversity and inclusivity and that are not offensive to other cultures - a trivial thumb up gesture or emoji may be misunderstood in Australia, Greece or Middle East.
• Do not expect that everybody knows referents originated in a specific cultural context. Give the full name of organizations and the abbreviated form in parenthesis. For people, places or events, some explanations or links to Wikipedia may be necessary.
• Use methods and tools that can be used, adapted or trained in a different language other than the language of your tutorial.
• Use methods and tools whose web interface and documentation are available in several languages.
• Support different character sets. If dealing with text processing, consider that most languages make use of non Latin characters as well as accents and various other diacritics.
• Be aware of cultural differences related to display capabilities, time and date formats, and personal names.
• Provide information and links to further resources and bibliographical references in several languages.

These key aspects are desiderable in order to make the localization process easier. Our editors will assist authors and reviewers and give appropriate feedback in case of doubt.

[arojascastro]

You may also be interested in this Internationalization Checklist by Windows: https://msdn.microsoft.com/en-us/library/windows/desktop/ee845046(v=vs.85).aspx

There are more tecnical stuff that you may want to include @mdlincoln @acrymble ...

[mdlincoln]

@arojascastro Thank you for drafting this. I really like this text - it is clear and covers many important issues, without being overly long.

Two thoughts

1. It might be useful to make even more explicit that we encourage for internationalization in both methods as well as sources. For example, if the text analysis tool you're using works for multiple languages, you might consider showing examples of source data from different languages, demonstrating any required configuration changes etc.
2. This text going in the reviewer guidelines, yes? I think it would make sense there, since that is where we already have many of our conceptual guidelines for lessons. The author guidelines specifically advise potential authors to consult the reviewer guidelines to understand what would make for a good lesson.

There are a few other small wording changes I might suggest - but I will put those in after you have opened a PR.

[arojascastro]

Thank you @mdlincoln for your feedback.

1. How would you make that more explicit? Would you add one more bullet item saying "We encourage for internationalization in both methods as well as sources. For example, if the text analysis tool you're using works for multiple languages, you might consider showing examples of source data from different languages, demonstrating any required configuration changes". Or would you add that idea in the first paragraph? For instance:

As the World Wide Consortium (W3C) reminds us, internationalization "is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language". Since 2017 The Programming Historian has become an international and multilingual website that provides lessons for English and Spanish audiences (February 2018). For this reason, we encourage authors to adopt an international outlook while writing their lessons in both methods and sources. Key aspects to be considered include but are not limited to:

2. I am not sure. I drafted this thinking that the author should read these guidelines before starting to write - but for sure the reviewers and editor should take them into account while reviewing proposals. If they are going to t be part of the reviewer guidelines maybe the text should be a bit different - instead of using the imperative form we should use questions. For instance:

   • Images, texts and datasets should be as cosmopolitan as possible accordingly with our global audience. Does the author use international resources well known all around the world?
   • Examples, representations, icons, symbols and colors are important. A trivial thumb up gesture or emoji may be misunderstood in Australia, Greece or Middle East. Do examples embrace diversity and inclusivity? Are they respectful and non offensive to other cultures?
   • Referents originated in a specific cultural context may be unknown for different audiences. Does the author give the full name of organizations and the abbreviated form in parenthesis? Are there explanations or links to Wikipedia concerning mentioned people, places or events?
   • Does the author use methods and tools that can be used, adapted or trained in a different language other than the language of your tutorial?
   • Does the author use methods and tools whose web interface and documentation are available in several languages?
   • Does the author support different character sets? If dealing with text processing, non Latin characters as well as accents and various other diacritics are covered in the tutorial?
   • Cultural differences such as display capabilities, time and date formats, and personal names are discussed?
   • Does the author provide information and links to further resources and bibliographical references in several languages?

I think this is an important issue because if we start adopting this criteria we will make translations and localization into Spanish, French or another language much easier and truly international. On the other hand, it requires that the team understands and supports these ideas and sees a real benefit in the long term. Asking for this kind of contributions to authors is going to be difficult because most of them will have to go beyond their comfort area and explore unknown territories -- for example, how many of our current tutorials contain bibliographic references other than in English? I would say none.

[arojascastro]

Bonus: I found this article about "Writing for a Global Audience" interesting. But I do not think we should go in that detail, right? https://www.globalme.net/blog/writing-for-a-global-audience-25-dos-and-donts

[acrymble]

This is an interesting discussion. I support it in principle (especially to get English speakers to think about the rest of the world when they write). But I am wary that we don't want to create a situation where local variation in needs and culture cannot be expressed. The DH skills needs of a place like Africa or S. America might be quite different from those of Europe. We wouldn't want a policy that prohibited or otherwise made it difficult for those different regional needs for different types of skills/tools to be published because they didn't necessarily meet the needs of other cultures and locations.

So we need to find a balance. And in the first instance, I think it should be something editors are responsible for considering as they conduct their first pass reviews, so we can see what effects it has (if any) on lessons.

[arojascastro]

True, I agree that local needs may differ but for that reason we are also asking for original tutorials in Spanish. The point of this draft is to make easy to translate texts from one language into another. The same would apply to original tutorials in Spanish - if we ever publish one and you translate it into English you will encounter with many problems. On the other hand, I have done a lot of research and I think this draft summarizies the current state of the art when trying to go international in order to enable localization. But yes it would be great to hear more opinions.

[drjwbaker]

@arojascastro Thanks for all the research done on this. Looks great. One comment. After "for this reason, we encourage authors to adopt an international outlook while writing their lessons. Key aspects to be considered include but are not limited to:" why isn't the first thing we say something about authors considering writing in their language of choice (or contacting the editor to see if that is possible)? I know there are big infrastructure complications for us here, but it seemed - to me - like the elephant in the room which we should at least address (~"we encourage lessons English and Spanish. We don't currently have infrastructure to support publishing lessons in other languages. However if you want to write in a language other than English and Spanish, contact the editors")

[arojascastro]

I agree with @drjwbaker, I like that clarification. By the way I saw that some lessons have been already translated into French...

On the other hand, I did not mean to castrate the "local" needs - none of these criteria should be compulsory but desiderable. Let's say that a tutorial focus on a resource available only in English and that the method only works with English texts. For me that is fine, but it would be good that the tutorial discuss the pros and cons and acknowledges this and tries to suggest alternatives or solutions. This would help a lot to translators. Why? Because then editors and translators do not have to 1. ignore problems and keep translating as it all was perfect; 2. or intervene, adapt and rewrite the lesson in order to solve those problems.

[acrymble]

I will use these guidelines as a talking point in the lesson I've just started editing. It's important that we don't change the goalposts for people further down the review process, but I think this is a positive idea. Thank you @arojascastro. Let's test it out and see how it goes before adopting it as formal policy (or adapting it before doing so).

[arojascastro]

Great! Let's test them and then adapt or propose a different approach. Let us know about the feedback from authors.

[arojascastro]

I am sorry to insist on this, but there are a few lessons under revision and I noticed that this issue was not considered. Maybe it is too late for taking this into account BUT it would be good to put it in practice and get feedback from authors and reviewers...

[drjwbaker]

You are right. We need to pick this up again. Perhaps we need some agreed text as a starting point for the call (https://github.com/programminghistorian/jekyll/issues/651#issuecomment-363722402 ?) and a sense of where it might fit into our existing guidelines (note some overlap with https://github.com/programminghistorian/jekyll/issues/378#issuecomment-369307840)

[acrymble]

@arojascastro if the lessons you're talking about are still under review (eg, the editor hasn't asked for an end to reviews), perhaps you could add a constructive comment or two so that editors can incorporate that in the revision? Our review process is open to anyone before the editor calls for a halt.

[arojascastro]

Yes, I thought so, I wanted to check here with you all -- I hope to be constructive... it's not my strongest skill.

[arojascastro]

My comments about Introduction to Stylometry w Python here: https://github.com/programminghistorian/ph-submissions/issues/147

[arojascastro]

Just for the record, I found two manuals that can be useful - I have not read yet, only skimmed:

• Style Manual For the presentation of English-language texts intended for publication by UNESCO
• THE WORLD BANK TRANSLATION STYLE GUIDE

I am hoping to read them in the following days.

[arojascastro]

It seems there is no interest in adding the text on internationalization and localization to our guidelines for authors, editors and reviewers and that the discussion has been broaded in https://github.com/programminghistorian/jekyll/issues/768 - so I am closing this. We can reopen in the future.

[acrymble]

I don't think that's true Antonio. But we have said we want to try these suggestions before we commit to changing (again) the guidelines. It takes months for a single lesson to go through a peer review, so this is something that will take time.

[arojascastro]

In my opinion, it does not make any sense to review submissions with those criteria if authors, editors and reviewers cannot access to them in the guidelines. It is going to be very difficult to put it in practice, but hopefully I am wrong.

[acrymble]

We've only had 3 submissions since you opened this issue. We can't change the rules for authors in the middle of a review, so you have to think longer term about this solution. There will be lessons that simply don't translate well. Especially those that focus on linguistics. That doesn't mean your idea for guidelines isn't great.

If you're looking for views on how to implement this, personally, I don't agree that we should be building in rigid rules. To nearly all of your checklist I'd respond by saying:

Our authors are historians and will be trained with particular resources and are familiar with particular approaches. They should feel empowered to use materials they have access to and know well. This is important because they need to understand the limits of their sources so that they can teach methods appropriately. It's also important to let them build their tutorials around their research interests so they can make a case to their employers for how their tutorial feeds into their wider research activity.

What we can do is ask them: "are there ways you could adapt your choice of tools and methods so that the lesson can be language independent? Can you add multi-lingual or multi-national references? Would a person in another country be inhibited in any way from making the most of this lesson as it is currently written? Is there a tool that does the same thing but is better supported for multi-lingual audiences?" If they can't address those types of questions for reasons related to the integrity of their approach/method/tool, then maybe the lesson doesn't get translated, and we can warn them of that. That doesn't mean it isn't useful for English readers.

In terms of 'rules', if we want to call them that, I think it's entirely reasonable to ask people to avoid jokes, obscure cultural references, etc. And to ask them not to assume people understand their acronyms, but that should be dealt with in the editing process anyway.

[arojascastro]

Why we cannot proceed as you did with the sustainability strategy? https://github.com/programminghistorian/jekyll/issues/534

We have rules on open access -- we only accept lessons on open access tools -- and we have recommendations on sustainability. Why this cannot be as smooth as that topic?

I understand your point that authors need to be comfortable and that English readers find helpful some tutorials that are addressed to them. That is all right. I do not agree that we should hide the fact that our readers are global and that we are hoping to translate lessons.

Can we just simply acknowledge those facts in the guidelines and act accordingly? Again, I think this should be as important as the sustainability strategy, which in my opinion did not cause any troubles.

[ianmilligan1]

I'll just quickly chime in to note that while #534 seems like a relatively quick discussion, it was part of something that was being discussed way back to 2016 – so well over a year and a half or so for changing our guidelines.

For what it's worth, I'm in favour of us thinking about this and taking our time. It's a potentially major shift and pushing our authors in different ways. That's fine, but as a volunteer-run site that depends upon submissions that have varying levels of currency within individual academic contexts (i.e. for promotion/merit/whatever), moving slow gives us a level of consistency, transparency, and predictability.

Preparing a lesson under one set of assumptions and then feeling castigated for not addressing one or two additional points doesn't provide the positive author experience we should be, in my humble opinion, shooting for.

[acrymble]

@arojascastro I believe we are proceeding as we did with the sustainability strategy. At the moment there are outstanding issues with your proposal that we need to proceed carefully with. We don't want to adopt a policy quickly and then regret it later.

I agree with a lot of what you've proposed. I think all of this is fine:

As the World Wide Consortium (W3C) reminds us, internationalization "is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language". Since 2017 The Programming Historian has become an international and multilingual website that provides lessons for English and Spanish audiences (February 2018). For this reason, we encourage authors to adopt an international outlook while writing their lessons.

I also think it would be fine to ask authors to consider if a person living on another continent would rasonably be able to understand the examples and references in their lesson.

But we also need to consider how we can achieve your needs (which I read to be lessons are easier to translate, and demonstrate an awareness of an international and multi-lingual audience), without falling afoul of any of the following:

1. Preventing the publication of potentially important or field-changing methods that perhaps do not have an easy-to-implement Spanish version. Particularly lessons that deal with text.
2. Expecting authors to master secondary literature in a foreign language that is beyond their ability.
3. Expecting authors to master primary sources outside of their area of expertise for the purpose of internationalisation, and at the expense of being able to demonstrate to employers how their tutorial fits with their research profile.

If you can start to address those issues, I'd imagine we can get this implemented sooner.

[arojascastro]

@ianmilligan1 I see your point but translations are also run on a volunteer basis. My job is taking care of the translating process and translators, who are also authors that work for free. It is true that we may lose some authors in America but maybe we gain others from different cultures and countries. For instance, I commented this review ticket and pointed out some internationalization ideas, and we found out that the author is Spanish and is willing to translate or adapt his lesson.

@acrymble it must be a collective effort, where authors, editors and reviewers take care of not only the tecnical aspects but sustainability and internationation problems. That is why somewhere else I suggested that we should expand our pool of reviewers and welcome editors with an international background.

(As a side note: as a Spanish scholar I am asked to master secondary literature in a foreign language. Not only English, but also French and German. Same applies with primary sources outside of my area of expertise. I think it is a default expectation in Europe if you are a scholar.)

Said this, my position is very clear and I am not going to comment any further. It is very tiring.

[acrymble]

@amandavisconti I think this could use some ombudspersoning. @arojascastro is clearly frustrated.

[arojascastro]

Going back to this, I took some days off to think about. I suggest someone else writes another proposal or adapts mine. I am a very open minded person and I am willing to accept a compromised set of guidelines that please everybody.

SO we could delete some of the most controversial items and get something like:

Internationalization and localization

As the World Wide Consortium (W3C) reminds us, internationalization "is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language". Since 2017 The Programming Historian has become an international and multilingual website that provides lessons for English and Spanish audiences (February 2018). For this reason, we encourage authors to adopt an international outlook while writing their lessons. Key aspects to be considered include but are not limited to:

• Images, texts and datasets should be as cosmopolitan as possible accordingly with our global audience. We recommend using international resources well known all around the world.
  • Examples, representations, icons, symbols and colors are important. We encourage seeking cases that embrace diversity and inclusivity and that are not offensive to other cultures - a trivial thumb up gesture or emoji may be misunderstood in Australia, Greece or Middle East.
• Do not expect that everybody knows referents originated in a specific cultural context. Give the full name of organizations and the abbreviated form in parenthesis. For people, places or events, some explanations or links to Wikipedia may be necessary.
• Support different character sets. If dealing with text processing, consider that most languages make use of non Latin characters as well as accents and various other diacritics.
• Be aware of cultural differences related to display capabilities, time and date formats, and personal names.
• Do some research and provide information and links to further resources and bibliographical references in several languages.

These key aspects are desiderable in order to make the localization and translation process easier. If source tutorials use methods and tools that cannot be used, adapted or trained in a different language it is likely that they will not be translated into another target language, but they will still satisfy their intended audience. Similarly, if authors are willing to see their tutorials translated, we recommend using methods and tools whose ocumentation are available in several languages. Our editors will assist authors and reviewers and give appropriate feedback in case of doubt.

I do not really like the language in the last paragraph, but I cannot work on this anymore.

Anyway, I encourage other people to publish their proposal in order to address this issue.

[amandavisconti]

Hello, all—thanks for having this conversation, and especially thanks @arojascastro for all the scholarly effort and care you've put into this.

tl;dr: I'm reading these as guidelines that we'll design so that folks do due diligence trying to follow (and record their reasoning when they can't), not rules. Can we see if any authors of in-progress lessons would be willing to spend 1 extra week (or less) thinking through these with us?

I haven't been on the associated editorial team calls, so my apologies for retreading anything that's been discussed. From reading over this thread, I'm seeing a possible miscommunication? The text @arojascastro originally suggests here (as well as the rewording for reviewer use here) reads as reasonable to me, and well in line with our existing text encouraging authors, reviewers, and editors to be thoughtful about accessibility and sustainability.

I don't see these ever presented as potential rules, in this thread—rather, they follow our "guidelines we strongly encourage, and thus work hard to help our authors achieve when reasonable" approach e.g. to open source software:

1. we explain why we prefer and encourage it, why it's better for our audiences;
2. we task authors with arguing why they'd need to use non-OS resources if they want to do so;
3. in particular cases such as the past lesson idea about setting up a digital preservation lab, we recognized when there are reasonable barriers to only using OS resources (e.g. that some means of migrating/preserving digital media such as VHS tapes are difficult to do for free), and work with the author to identify the best possible means of making these lessons accessible to the most people (e.g. explain how to get in touch with local city librarians or nearby community colleges to ask to borrow their equipment; explain why the non-OS/non-free software is necessary, and identify any OS software that could help the reader achieve at least parts of the lesson).

I'm personally excited to see us building out our recommendations of how to best support our readers. As we consider adding guidelines like these, the editorial team might:

1. present our growing set of guidelines so they're easy to skim (and be aware of while beginning to write a lesson) as well as work through during polishing/review (e.g. create a GitHub issue template formatted as a checklist for addressing each suggestion/question?)
2. create a reminder (again, maybe just part of a GH issue template?) for editors to lead authors and reviewers of a lesson through recording any discussions/decisions made in response to these guidelines; the editorial board could then schedule time during the editorial call every 6 months to review these arguments and identify any problems in these answers (e.g. checking whether due diligence was actually performed, recommending widely useful resources like Europeana rather than Internet Archive, helping identify search terms or tweeting via the ProgHist Twitter handle to locate resources outside the authors'/editors' local context
3. think about the value of these guidelines as scholarship (e.g. perhaps a co-authored journal article glossing these guidelines and the discussions that go into them? adding reminders to @walshbr's great Twitterbot to check out the guidelines page, as a growing scholarly resource just as important as our lessons?)
4. outline a clear process for moving forward with guideline suggestions like these (e.g. new guidelines are led/advocated for by an editorial team member => discussion at next editorial call => identification of which lessons to try these with => mutual agreement on what lesson outcomes would support/question formal adoption of these guidelines in the future)

A strength of the volunteer, non-anonymized effort that goes into ProgHist is that we're all—authors, reviewers, editors—trying to make something together, with the same goal of sharing DHy knowledge. I applaud everyone's care that the authorship process does not become unnecessarily stretched out.

However, I'm not sure I see a problem with testing out these guidelines now, with lessons currently in the pipeline—can we just ask the authors of lessons in progress if they'd be willing to help test these out, with the assurance we'd spend no more than one extra week doing so? We could be clear that these are potential guidelines (not rules), and that given these guidelines weren't in place when the authors began, we won't let this work take more than one extra week of their time.

This will let us both honor our agreements with authors of lessons-in-progress, and the work that @arojascastro has put into creating these guidelines. (I'm a bit concerned that if we don't at least ask current authors if they'd be willing to try this, it isn't clear how/when we'd remember to tell potential authors of new lessons about these guidelines, since they're not on the site yet. This ticket was opened in November 2017, and at this point I'd like to see something in place to make sure we do try these out with the very next lesson, if not the current in-progress lessons.)

If I'm interpreting things correctly, @acrymble, I think these guidelines should not conflict with the three concerns you shared here. Thanks for thinking through the repercussions of these guidelines—it's important to document these so we can periodically check that they aren't occurring. If we think of these as strongly encouraged and strongly supported (by the editorial team, by asking for help/resource suggestions from our Twitter followers, etc.), I don't think we're tasking our authors with too much, and I don't think we'd be preventing important work from being published. Perhaps we can use the next three lessons as case studies?

Thanks, all who made it through reading all this, and all who didn't but contributed to this discussion too! (This text wall courtesy of cold meds and a nasty sinus headache.)

Bonus tiny question: @arojascastro pointed out that the thumbs-up sign is inappropriate for use with an international audience, and I noticed GitHub issue reactions are somewhat limited in this regard (e.g. I have thumbs-upped comments in this thread). Wondering whether we want to encourage use of the "hooray" reaction instead of the "thumbs up" one, add a comment about this on our site (since we use GH so heavily), and/or something else.

[arojascastro]

Thank you @amandavisconti for your careful reading and kind words. I really appreciate that you see my proposal as a scholarly contribution (I had to read a lot of articles to summarize the main ideas) and that you see no danger. I also thank you for putting this into the agenda, encourage people to test the guidelines and set following up steps for including them in the general guidelines. Otherwise, I was feeling a bit frustrated for the work done.

I apologize if I was too tough or if I did not communicate properly. I think the problem might be written communication that makes me sound more assertive than I am actually. That is why emojis are so important in on line communication. I talked to some colleagues from Greece when I wrote that proposal and they confirmed that the thumb up is like a middle finger. However, nowadays because of globalization, very few people would misunderstand that symbol in a real life interaction where you can see the facial expression. @amsichani can also give us her view on this since she is Greek. In any case, we can change that example if you think it is very extreme.

[amsichani]

I am generally in favour of avoiding emojis with body language gestures esp. in written communication. I think this is also the consensus among designers: emojis were supposed to be the great equalizer, capable of transcending borders and cultural differences. BUT thats not always the case . I can confirm that coming from a double origin background (Greece and Egypt) I am always having trouble with gestures and their explicit or symbolic meaning, both in written and oral communication: "thumbs up" in GR and Egypt can be seen also as a middle finger (though in nowadays younger people more often use it as an approval symbol), and "extend your hand,palm outward - high five" in GR is something close to 'shit in your face' (mountza) [pardon me]. I second @amandavisconti on trying to encourage alternative - non-culturally sensitive emojis in our internal GH communication and to write a small comment on our site or a blogpost on this. In my view, this stands as a great step within the spirit of our internationalisation agenda. We can't (?) change GH emojis options, but it's important to raise the issue here.

[acrymble]

Thanks @amandavisconti. That sounds very reasonable to me.

I'll try to be productive, and suggest an amended version of @arojascastro 's original text, with the idea of keeping the guidelines terse but clear, and also trying to make sure they wouldn't put off an anglophone contributor not used to thinking about these issues:

I would expect this to go in author's guidelines under 'Write Sustainably'.

---

Write For a Global Audience

Programming Historian readers live all around the world, and operate in a range of cultural contexts. To help reach that global audience, we have been publishing in more than one language since 2017, and aim to translate all tutorials. Authors can and should take steps to write their lesson in a way that is accessible to as many people as possible:

• When choosing your methods or tools, make choices that help multi-lingual readers or those reading a translation to make the most of your tutorial. This is particularly important when working on textual analysis methods, or where users may reasonably want to have support for different character sets (eg, accented characters, non-Latin, etc.).
• Where possible, choose methods and tools that have multi-lingual documentation.
• When choosing primary sources, we encourage authors to use materials they know well, but where possible they should make choices that are internationally focused and that could reasonably be used in translated lessons.
• When choosing images, producing figures, or taking screen shots, consider how they will present themselves to a global audience.
• When writing, avoid jokes, cultural references, puns, plays on words, idiomatic expressions, sarcasm, emojis, or language that is more difficult than it needs to be. Mentions of persons, organisations, or historical details should always come with contextual information. It may help to assume your reader does not live in your country or speak your language.
• Use internationally recognised formats for time, dates, etc.
• Where possible, further resources and bibliographic references should be to multi-lingual sources.

Contact your editor if you require guidance on any of these matters. Tutorials that are unable to meet these guidelines may not be translated.

[acrymble]

I second trying this out on the next 3 lessons to come in.

[arojascastro]

I am happy with those changes / adaption @acrymble. Would you add anything to the guidelines for reviewers and editors as well? I also think it is good to try out this on the next 3 lessons to come in. Should we ask for more feedback from people who have not contributed yet or we simply decide it is good enough?

[acrymble]

Can we wait till the meeting? This is on the agenda. #777

[acrymble]

Please comment on this by 7 May 2018 if you have any further thoughts. Otherwise, I will open a pull request for the above text, and will include similar content for the editors and reviewers as per @arojascastro 's suggestion.

[mariajoafana]

For the first item in the list I would day: Each language has its complexities and there is only so much that the author of a tutorial can do with the constraints of the platforms, programming languages, etc. This makes me think that the guidelines may deal with specific topics. Something like: "For tutorials focusing on textual analysis we recommend x, y, and z".

For the item: "Where possible, choose methods and tools that have multi-lingual documentation", although this is ideal, I think is kind of unrealistic. We want to write for a global audience but most of the documentation, platforms and programming languages are only in English. I would phrase this like this: When possible, add a multi-lingual documentation section ("Further reading" or "References") at the end of each tutorial. This is already addressed in the last item of the guidelines.

On the primary sources issue, what does it mean to choose primary sources that are internationally oriented? and that "could reasonably be used in translated lessons." It might be useful to give an example here. We could unpack this discussion a bit. For example, each set of primary sources is unique, historically-bound to a context and mechanism to access it. Primary sources are found in digitized versions at the different levels of access and possibilities to obtain and manipulate its metadata. On tutorials that deal with the automatic downloading of bibliographic data from online collections, this poses larger problems. For example, some testing needs to be done in order to find Spanish-language digitized databases that are able to be downloaded automatically. It is my sense that infrastructure for accessing and downloading large collections metadata is lagging behind in Latin America. I guess there are structural problems here and the stage in which DH is right now in the region.

We don't want to reject tutorials that are difficult to translate but can be useful to a number of readers, but at least we want to think of this issues early on in the acceptance of a tutorial proposal and the review process. However, now that we are just beginning to encourage the publication original tutorials in Spanish I worry that some of this guidelines would be a burden for our possible new authors. I think that we need to think beyond writing tutorials that are easily translatable, and maintain a balance between local-specific tutorials, and tutorials that have a global outlook. I don't think that all tutorials can hold a high standard in terms of internationalization. We might have a more complete image of all this once we start receiving original tutorials in Spanish and thinking about their translation into English.

[drjwbaker]

We don't want to reject tutorials that are difficult to translate but can be useful to a number of readers, but at least we want to think of this issues early on in the acceptance of a tutorial proposal and the review process. However, now that we are just beginning to encourage the publication original tutorials in Spanish I worry that some of this guidelines would be a burden for our possible new authors. I think that we need to think beyond writing tutorials that are easily translatable, and maintain a balance between local-specific tutorials, and tutorials that have a global outlook. I don't think that all tutorials can hold a high standard in terms of internationalization. We might have a more complete image of all this once we start receiving original tutorials in Spanish and thinking about their translation into English.

This is the reason - initially - why I urged delay and learning from the ES work planned for this year (and incoming FR work) before adjusting our documentation. However when @amandavisconti intervened (very helpfully) at https://github.com/programminghistorian/jekyll/issues/651#issuecomment-380259329 I accepted the need for more immediate change that @arojascastro. So I'm now confused. Is there an interim change we can make that would satisfy some concerns, and save the larger changes for after we've been through the AMAZING internationalization work we have planned for this year? (to recap: survey, DH, Bogota, first ES lesson, FR initiative)

[acrymble]

Ok if I read @drjwbaker and @mariajoafana correctly, the request is to tone down the requirement a bit, so that we don't cut out potentially useful lessons, at least until we better understand the repercussions of this new policy. Revised with that in mind:

Write For a Global Audience

Programming Historian readers live all around the world, and operate in a range of cultural contexts. To help reach that global audience, we have been publishing in more than one language since 2017, and aim to translate all tutorials. While we recognise that not all methods or tools are fully internationally accessible, authors can and should take steps to write their lesson in a way that is accessible to as many people as possible. Please consider the following when writing your tutorial:

• When choosing your methods or tools, try try to make choices with multi-lingual readers in mind. This is particularly important when working on textual analysis methods, or where users may reasonably want to have support for different character sets (eg, accented characters, non-Latin, etc).
• Where possible, choose methods and tools that have multi-lingual documentation.
• When choosing primary sources, we encourage authors to use materials they know well, but where possible they should make choices that are internationally focused and that could reasonably be used in translated lessons.
• When choosing primary sources, images, producing figures, or taking screen shots, consider how they will present themselves to a global audience.
• When writing, avoid jokes, cultural references, puns, plays on words, idiomatic expressions, sarcasm, emojis, or language that is more difficult than it needs to be. Mentions of persons, organisations, or historical details should always come with contextual information. It may help to assume your reader does not live in your country or speak your language.
• Use internationally recognised formats for time, dates, etc.
• When possible, add a multi-lingual documentation section ("Further reading" or "References") at the end of your tutorial.

Contact your editor if you require guidance on any of these matters. Tutorials that are unable to meet these guidelines may not be translated, but are still welcome for consideration for monolingual publication.

[drjwbaker]

If @mariajoafana @arojascastro (that is the ES members who've commented on the ticket) are happy, then I am. Thanks Adam for the revision.

[arojascastro]

I am a bit surprised because the first original proposal that we received precisely uses a tool that works with English, Spanish and Japanese and whose web interface is available in three languages.

I recommend people to read the tutorial about "Stylometry with Python" where we put these ideas into practice. I think the final output is much better after considering these issues.

I agree about the balance between local needs and global coverage, however, these guidelines are not dangerous at all and they have a heuristic dimension as well -- we as a DH project stand for these values and help to change the statu quo. I see translation as an agent of change and to be honest I am less interested in fullfilling local needs than serving as a communication enabler between communities -- that is why I tend to favour translations rather than original content. But this is just my opinion and you may have other preferences.

Said this, I am happy with any text that addresses the problem and allows us to move on. I am also confident that we can change these guidelines or improve them in the future when the English team starts translating from Spanish.

[drjwbaker]

@arojascastro To clarify, when you say ..

I am a bit surprised because the first original proposal that we received precisely uses a tool that works with English, Spanish and Japanese and whose web interface is available in three languages.

.. what are you referring to here? The first ES proposal that has been received?

[arojascastro]

Yes, exactly, by we I meant the Spanish team. The author is sending the final proposal in the following days.

[drjwbaker]

Thanks for the clarification @arojascastro.