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

[walshbr]

Just explicitly saying here that I support this and the conversations around it. Have been keeping silent because the other opinions rendered here have been very thoughtful and useful - I trust your judgements. The new text looks good to me. As I mentioned on the call, guidelines like these are also helpful for new editors as we try to find specific points of intervention with new proposals.

[arojascastro]

Just let me add three things.

In my original proposal, I stated the following:

• 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.

In the latest proposal we have:

• 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.

The first bullet is the opposite of what I meant. What I meant is that there is no standard dates or times and thus the author should cover a range of different formats. For instance, in British English you may say 14th March 2016 but in American English you might say March 14th, 2016 and in Spanish 14 de marzo de 2016 while in German is 14. März 2016 (if I am not wrong).

Something similar happens with personal names: you have one family name whereas in Spain we have two.

In respect of the second bullet point, I am not sure adding an appendix is a solution: a global outlook should not be something that you add as suplemment or an amendment, it should be something that is organically present in all the tutorial.

Also in my original proposal there was a inclusivity component that has been lost: "We encourage seeking cases that embrace diversity and inclusivity and that are not offensive to other cultures".

We have also lost the links to W3C on internationalization: https://www.w3.org/International/questions/qa-i18n.en

But as I said, at this moment I am happy with any text that reaches a consensus.

[acrymble]

Sorry @arojascastro I guess I misunderstood.

For the first one, is this something that authors can actualy follow? Other than making them better people, what will being aware of different ways of showing the date do to the lessons?

• Be aware of cultural differences related to display capabilities, time and date formats, and personal names.

[drjwbaker]

On ..

Use internationally recognised formats for time, dates, etc.

.. can we resolve this by making a distinction between dates/times in free text and dates/times in code or metadata.

So, for dates in free text we accept that there are many ways of representing dates or times.

But for dates/times in code or metadata there are international standards that are useful for ensuring interoperability of code/metadata and that I recommend we use. Specifically, I refer to ISO 8601:2004 - Data elements and interchange formats -- Information interchange -- Representation of dates and times (see https://www.iso.org/standard/40874.html or https://www.loc.gov/standards/datetime/iso-tc154-wg5_n0039_iso_wd_8601-2_2016-02-16.pdf).

[arojascastro]

Absolutely @drjwbaker

I took the idea from W3C: https://www.w3.org/International/articles/definitions-time/

I guess this is relevant if we expect tutorials that need input from users (for instance, forms) or about web design. It may be less relevant in text analysis -- but maybe those tutorials focuse on creating a list of dates using XSLT, python or R as well. In any case, if you think it is not relevant, we should remove that bullet.

Have a nice day.

[drjwbaker]

• 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).
• 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.
• In code or metadata, use internationally recognised standard formats for dates and times (ISO 8601:2004). In free text, be aware of cultural differences related to the representation of dates and times.
• When possible, add a multi-lingual documentation section ("Further reading" or "References") at the end of your tutorial.

[acrymble]

Ok continuing to revise based on feedback:

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 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.
• In code examples or metadata, use internationally recognised standard formats for dates and times (ISO 8601:2004). In free text, be aware of cultural differences related to the representation of dates and times which might cause confusion.
• Where possible, choose methods and tools that have multi-lingual documentation. If this is not practical, it would be great if you could add some multi-lingual 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.

[jenniferisasi]

I like this! Only, on "When choosing your methods or tools, try try to make choices with multi-lingual readers in mind." there are two "try"

[arojascastro]

I just want to add that I'm very happy with the final proposal -- it is better and more balanced than my original text. I thank you all also for the collaborative spirit of this issues. You helped a lot to shape my thoughts and I also learned and changed my perspective thanks to your criticisms and comments.

[drjwbaker]

I feel the same @arojascastro. This has been an excellent, passionate, therapeutic discussion.

[acrymble]

I have created a pull request. This is awaiting translation before being published. Thanks for your views everyone.

[arojascastro]

Thank you! I can translate the texts on the weekend -- unless someone else can / want.

[acrymble]

It would be great if someone else on the Spanish team would help with this. We rely on @arojascastro a lot for this type of work. I'm sure he would appreciate more help.

[jenniferisasi]

@acrymble and @arojascastro here is a preliminary version of the translation; in this manner, I hope someone can review it and make the necessary changes and paste it where appropriate cos I'm not sure where this goes and last thing I want is break the guidelines website :)

Escribir para una audiencia global

Los lectores de Programming Historian viven por todo el mundo y, como tal, trabajan en un amplio rango de contextos culturales. Para poder alcanzar a dicha audiencia global, hemos estado publicando en más de un idioma desde 2017 y nuestro objetivo es traducir todos los tutoriales. Aunque reconocemos que no todos los métodos o herramientas son totalmente accesibles a nivel internacional, los autores pueden y deben tomar medidas para escribir sus lecciones de manera que sea accessible al mayor número de personas posible. Por favor, considera lo siguiente al escribir tu tutorial:

• Al elegir tus métodos o herramientas, toma tus decisiones con una audiencia multilingüe en mente. Esto es particularmente importante cuando se trabaja en métodos de análisis textual, o cuando los usuarios quieran tener soporte para diferentes conjuntos de caracteres de forma razonable (por ejemplo, caracteres acentuados, no latinos, etc.).
• Al elegir tus fuentes primarias e imágenes, al crear figuras o al hacer capturas de pantalla, considera cómo se presentarán a una audiencia global.
• Al escribir evita usar chistes, referencias culturales, juegos de palabras, expresiones idiomáticas, el sarcasmo, emojis o un lenguaje innecesariamente complicado. Las menciones a personas, a organizaciones o a eventos históricos siempre deben ir acompañadas de información contextual. Te puede resultar útil pensar que tu audiencia no vive en tu país o que no habla tu mismo idioma.
• En tus ejemplos de código o metadatos, utiliza los formatos estándar internacionalmente reconocidos para fechas y horas ([ISO 8601: 2004] (https://www.iso.org/standard/40874.html)). En tu texto, ten en cuenta las diferencias culturales relacionadas con la presentación de fechas y horas que puedan causar confusión.
• Cuando sea posible escoge métodos y herrramientas que tengan documentación multilingüe. Si esto no es posible, trata de agregar algunas referencias multilingües al final de tu tutorial.

Contacta con tu editor si necesitas orientación sobre alguno de estos asuntos. Puede que no podamos traducir tu tutorial si no cumple con estas pautas, pero aún así lo consideraremos para su publicación monolingüe.

[acrymble]

I've added this to the pull request. Just need a reviewer to look it all over.

[arojascastro]

I can take care later today.

[arojascastro]

Done.

[acrymble]

Thanks everyone, and especially @arojascastro for this important policy change.