User:Contraexemplo/Outreachy/Daily notes/December 2017

How to become a volunteer?
The first question that needs to be asked when we talk about recruiting more volunters should be: is the process of becoming a volunteer clear? One of the things I noticed as I read all the documentation available for translators is that it doesn't state how to create an account and get a translator permission to begin contributing.


 * meta:Meta:Babylon/Translations is an excellent page to introduce new people to the process of translation on Wikimedia. But even though it's arguably less confusing than the Extension:Translate page, it doesn't include that valuable information (and this is going to be addressed and corrected soon). However, this situation is just a symptomatic indication of a bigger problem: the uncertainty of the profile of those who read the documentation. From what I saw and read, wikimedians will deal with the current state of documentation with ease while non-wikimedians will get lost.

In a way, being a person not so familiar with the way Wikimedia functions works in my favor: while Johan and Benoît have years of experience under their belt, I have the perspective of someone who is confused with the complexity of the projects. This makes me easily perceive what is missing to understand clearly the path I need to make to become a contributor and to make outstanding contributions.

By the way, about the documentation...
MediaWiki.org already has a Documentation Style Guide describing best practices when writing and formatting documentation. However, I think its presentation could be done better and more information can be added. Take, for instance, Atlassian's Style Guide. It's brief, but presents information in such a way the reader doesn't need to think much: it has tables comparing bad and good practices and explanations about why they chose do adopt certain patterns. This is an excellent way to set a quality standart to everything that needs to be written: it's a clear, quick and effective read.

Today I was also reading (and honestly admiring) the documentation written by and aimed for the localization team of Mozilla. This one, for example, is aimed for Brazilian Portuguese translators. Take a look into how welcoming and organized the page is. It presents all meaningful information that is needed to become a translator and introduces the community involved directly with this task at the same time. Well, what in this documentation makes it so well written?
 * 1) Its landing page is brief. The objective of it is to gather all information that may be useful to those who want to begin contributing: where to contact the team responsible for this kind of work, how to join it, what are they doing, how to start contributing and what resources are relevant.
 * 2) Their glossary has an interesting structure. In Portuguese, words have gender. Not only they provide the appropriate translation to a word but they also give the reader an example of the context it is used and its gender. This normalizes the translation, making it more cohesive. I'd go further and provide a list of synonyms that can be used on longer texts (for instance, espaços de nomes and espaços nominais refer to the same thing [namespaces] without losing the real meaning in the translation). (There is a task on Phabricator to make something similar to the Transvision Glossary used by Mozilla, by the way!)
 * 3) They have facilitators to help newcomers to settle down. This is important for two reasons: one, it helps people to perceive that nothing happens by magic. Things are build by the effort of thousands of volunteers and citing them makes this crystal clear. Two, it creates a bond with the existing community and motivates newcomers to stay because of this bond. I may love the tools, the projects, the software, but I stay because I feel welcomed and belonging. This is exactly what community identification is about.

How to attract new people?
If that answer was obvious I probably wouldn't be here.

I was talking about some of the results of a preliminar survey I made before being selected to the internship on the meeting today when Benoît pointed out the New Editor Experiences page. Their findings resonate with a lot of my hypotheses and this is really reassuring. The problem, though, is that it's more easy to point out what is wrong than to find out how to solve it. And finding some of the answers is exactly what my work is about.

Questions to think about tomorrow

 * How can I help improve the documentation? I need to gather resources concerning content and presentation. For that, I'll contact people who are used to work with it and keep reading other FOSS projects' documentation.
 * How can I build bridges between people who are already wikimedians and newcomers? It was quite difficult to find my local community so I think this is something I need to put some effort on. There are also some ways to talk with only wikimedians who deal with translation but are they universally accessible and easy to find?

"How to start" page
After some searching I finally found a page talking about how get started to become a translator at the adequate wiki: translatewiki:Translating:How to start. However, it still feels... incomplete? There's a lot of "do this", "do that" but good resources to empower translations are missing and it still presumes you are familiar with the whole process of contributing. And once again, I feel like valuable information is all over the place. But as I said yesterday, meta:Meta:Babylon/Translations is a good immediate solution to this. I need to find ways to improve it and make it even more suitable to newcomers.

Path to become a translator

 * 1) You go to translatewiki.net and make an account stating the languages you know, choosing an username, password and e-mail to register.
 * 2) You need to make some translations to complete your registration. You click in "Translate" and is redirected to page designated to teach you how to use the tools. I made an account for testing and I had to reach the limit of 20 translations until the page stated it was enough. Now I need to wait to have my translations verified and be granted a translator permission. (It was 10:28 AM here in Brazil when I completed the training, let's see how much time is needed for that).
 * 3) Follow-up: it took less than 40 minutes (according to the e-mail I received, the translator permission was granted at 10:59 AM). The account is now ready to go.

Core problems
I'm getting to the conclusion that whatever I read will have the same core problems: So I think I'm finally beginning to find out what needs to be my focus throughout the internship. I'm aware those three things are related to the way Wikimedia was built and by now they are part of its culture, but there has to be a way to mitigate its consequences with immediate solutions and long-term care.
 * 1) Information is too fragmented.
 * 2) There is a lot of assumptions and the most troubling one is presuming you are familiar with the way Wikimedia works.
 * 3) Good resources to establish a quality standard are missing.

Pages and resources for translators

 * MediaWiki:
 * 1) Help:Extension:Translate/Translation example.
 * 2) Help:Extension:Translate/Translation best practices.
 * 3) Help:Extension:Translate/Statistics and reporting.
 * 4) Help:Extension:Translate/Quality assurance.
 * 5) Help:Extension:Translate/Message group states.
 * 6) Help:Extension:Translate/Off-line translation.
 * 7) Help:Extension:Translate/Glossary.


 * TranslateWiki:
 * 1) translatewiki:Translating:How to start
 * 2) translatewiki:Translating:Intro
 * 3) Localisation guidelines
 * 4) FAQ


 * Meta-wiki:
 * 1) meta:Meta:Babylon/Translations/New translators
 * 2) meta:Meta:Babylon/Translations
 * 3) Technical Collaboration/Community collaboration in product development/Tech ambassadors and translators (+ Tech/Translators/List)


 * Newsletters:
 * 1) Newsletter:Translators


 * Mailing lists:
 * 1) Translators-l

List of tasks to complete until the end of the week

 * Read all the pages and resources listed in the previous note.
 * Make anotations about the current state: what assumptions does it make? Is the aimed public clear? Was it translated? If so, to how many languages?
 * Keep searching for localization related resources in other FOSS projects. What points do they have in common? What patterns do they follow?

Brief follow-up about the path to become a translator
I updated Path to become a translator with more reliable information about how much time it took to receive a translator permission on my account for tests.

I didn't remember you receive an e-mail telling you that your translations were verified and you were granted translator rights so it was good to redo the whole process. More importantly, I didn't remember exactly what is said in this message and reading it again gave me some new questions to think about.


 * 1) Would it be useful to remind new translators of all the documentation available for them in this e-mail?
 * 2) What about connecting them with other translators of the same language? (Related: SupportedLanguages on MediaWiki.org)

Active tech translators
I got curious about the role and now I've got more reading to do. Related pages and discussions:
 * Coverage of technical translators for the top 25 Wikimedia projects
 * Top 25 wiki projects in terms of active contributors have at least one active tech ambassadors and one translator identified
 * meta:Talk:Technical Collaboration/Community collaboration in product development/Tech ambassadors and translators

Searching for more things, I've found this: ...which led me to this:
 * Translation coordinators per language
 * Translation teams

This is really interesting and talking to some of the people involved may be useful to get a broader perspective since right now I have only the perspective of a translator (myself). So here is more things to think about: what are the right questions to do? What should I be aware of? Most importantly: how can my work help them and how can their work help me?

Manuals of style for each language
Benoît proposed a demo so I'd know details about the translation process. He mentioned this task and since I like to explore a bit, I ended up reading past discussions and taking a look into this other task. One comment caught my attention: the one mentioning Language guides. I shared that with them and received an answer mentioning Wikimedia:Manual of Style. I mentioned on I was looking for ways to define a standard for documentation and this is exactly one of the things that I wanted!

I also need to correct myself. In Core problems, I wrote "Good resources to establish a quality standard are missing" but that's incorrect because it gives you the impression they don't exist. What I'm beginning to figure out is there are good resources out there, but people aren't aware of them since important documentation doesn't mention them explictly.

Indirect outreach
I'll have to travel unexpectedly to another state next week and what could be a push back to my internship will end up being a great opportunity: the local federal university offers a translation degree and there's a good chance I will be able to talk with them about the translation process at Wikimedia projects and what we could do to improve quality assurance on documentation and translations themselves. I also sent a similar e-mail to the people responsible for degrees related to foreign languages at the university I attend. Now all I can do is wait for their responses.

Quality assurance
As I was using translatewiki yesterday, I noticed it gave me some status about reviews and translations I made. One thing surprised me: it said I was the only person reviewing content in Brazilian Portuguese. This made me think about how important to the translation process is the reviewing work already done.

That reminded me of discussions questioning the importance of the translation of certain pages. Some people said it is better to read the source content than to rely on a translation that may be inaccurate. I can certainly understand where they are coming from, but from my perspective, this is a point of view ingrained with some privilege: this isn't a choice everyone can make. Some people simply haven't learned English and some, even though they can speak it, don't feel confident enough about their reading comprehension (I mean, I am a fluent speaker myself according to exams like TOEFL ITP and even I have some insecurities because I am an autodidact!). And, as I stated on my proposal, that also isn't compatible with WMF's core principles.

So, is a not-so-accurate translation better than an accurate one? Well, actually, the question that should be asked instead is: what is an accurate translation? Is it how much it matches with the source content word by word? Or is it about meaning? To me, if the text is conveying the intended message without losing anything, it certainly fullfilled its purpose. And when we give translators good resources (glossaries, manuals of style, support from the community), they are one step closer to doing that.

(Note: Reviewing is important, but is it realistic to worry about it, considering the current state of user guide translations? For now, I don't think so.)

Mastodon & Weblate
As you are reading this note, a translator community for Mastodon is growing -- Eugen finally decided to make the translation process more accessible! He chose a translation system called Weblate and made it available for everyone two days ago. It might sound off-topic, but getting to witness this change will give me more insight about other translation plaftorms and how translation teams are born and communicate with each other. It will also help me think about what questions I should ask to Niklas when we meet each other.

LibreOffice documentation
I began to read LibreOffice's Style Guide for documentation and some things already caught my attention:


 * Additional recommeded documents:
 * 1) The Chicago Manual of Style. University of Chicago Press.
 * 2) Read Me First! A Style Guide for the Computer Industry. Sun Microsystems.
 * 3) The Modern Language Association (MLA) guidelines.


 * Advocating for Plain English and giving tips to keep phrases simple ("use short, simple, easy-to-understand words").


 * Emphasis on the importance of gender neutral writing.
 * Stardards for dates formats, time, holidays and seasons.
 * Strict rules for capitalization and lists presentation.


 * Precise definitions of "tips" ("describes practical but nonessential information that does not otherwise fit into the flow of the text"), "notes" ("to break out related, reinforcing or other special information") and "caution" ("is mandatory text that you must provide to protect the user from injury or the hardware/software from damage").


 * Rules about where and how to use and display an image.
 * Conventions about which English use (both for spelling and punctuation).

Most of those things are lacking on Documentation/Style guide... And those are only the first six pages of their guide. I'll now read the Writing Style section more carefully and hopefully it will give me even more insights.

Meeting discussions
Had a meeting with Johan today and made some questions I've been thinking about throughout the last week. First and foremost, I needed to know what is their definition of "User guides". I re-read the task Johan wrote for Outreachy and I noticed it's quite vague about it. He explained what some namespaces are about and said he felt that the "Help" namespace is the one that fits the definition better, but we should talk to Benoît about that as well just in case he has something different in mind. (December 12: He confirmed it, so my focus will be the Help namespace).

I talked about some of my findings, like Core problems, Quality assurance, Path to become a translator and Active tech translators. I just wanted to make sure we were on the same page about everything and he was aware of what I am aware of... And I ended up discovering that I stumbled upon some of the old initiaves that took place some years ago, authored by people that are inactive for quite some time. Unexpected but really interesting.

As I stated on How to become a volunteer?, meta:Meta:Babylon/Translations is a good simplified way to introduce newcomers. It will be probably be our "landing page".

We also discussed how we could build strategies. He said he felt like we should focus on people who aren't involved with Wikimedia Foundation, especially because those people are already dedicating their time doing something else and having new volunteers is always welcome. I absolutely agree with him on this. I'm thinking about defining three different strategies directed to three different kinds of people:


 * 1) Those with no involvement with FOSS (as user and/or contributor) and no involvement with translations.
 * 2) Those with involvement with FOSS (and/or technical knowledge).
 * 3) Those with involvement with translations.

Note: The last two groups aren't mutually exclusive.

We talked a little about community bonding. We both agree the mailing list is probably the most accessible option to reach other translators since IRC is a little more complicated for those who aren't familiar with it, but he said he would speak with others to know if their opinion is the same.

I was also thinking about three levels of initiatives:
 * 1) Local.
 * 2) Continental.
 * 3) Global.

Note: They should easily reproduced by anyone who takes interest in it and not limited by what I can do physically. They aren't just global because I think they should be able accommodate cultural differences. But I need to have in mind I may not be able to do such extensive work during my internship, I need to focus on what is realistic: probably just local in my home country and global initiatives. This will probably be just a recommendation on my final report.

I actually avoided doing more specific questions about translatewiki and the translation process because Benoît is going to make a demonstration tomorrow and this is probably going to answer some -- if not all -- of them. This will help me out with the strategy building as well, hopefully.

December 12
Had some problems with power outage in my house yesterday and today so I've been reading documentation and working mostly offline with my phone by my side in case I need to talk with someone and going somewhere else when videoconferences are necessary. I'll transcribe the notes I've been taking soon.

Presentation about the Translation extension
Benoît made me a presentation about the Translation extension to get me more familiar with the tools and its technicalities (the same that is mentioned here). It was actually pretty much enlightening! I wasn't aware of how to mark a page to translation and how the software make those tasks easier -- I've read only the documentation regarding the translation process from the point of view of the translator --, so I learned a lot. Now I know:


 * 1) How to prepare an article to receive translations.
 * 2) Best practices when organizing its structure.
 * 3) What some of the indicators and identifiers in the UI actually tell the translator.
 * 4) How those end up in the UI from a translator admin stand-point.

What is next?
I want to read the documentation targeting translation admins (maybe some of them for developers that may be relevant? I don't know, I'll focus on the translation admins documentation first) and set up a page to test some of the functionalities and understand them better. I believe it's important to have in mind the whole translation process when thinking about strategies to improve the translations rate and bring more translators to the Wikimedia movement.

Why? Well, one of the things I pointed out in my proposal is how some [translatable] pages refer to other pages that are only available in English. Since we defined that our focus will be on the Help namespace, as a part of the preparations for new translators I need to verify if every single one of the pages is actually marked for translation.

Trip to next state
I had to take a trip during this period for personal reasons, as I stated in Indirect outreach. However, I used that as an opportunity to visit the local university and see if I could talk with people related to the Translation degree offered there. Unfortunately, the coordinator was on a trip as well, but I talked with a person who takes care of administrative affairs. Some interesting things:


 * They talked to the coordinator about my visit and gave me their e-mail. We're now in touch.
 * When I asked if undergrads would have interested in the activities I'm promoting, they said yes.
 * To prove they worked as translators, the university asks for a certificate (I'm working on knowing what are the minimal requirements for one).

But here's what really caught my attention:

Junior enterprises
They have a Junior enterprise. BUT:
 * 1) only a few people are able to participate.
 * 2) by law, they are required to work as volunteers.
 * 3) they don't have a HQ at the university because most of their work is done remotely and they rarely meet in person.

Why is the fact they do volunteer work so important to me? Brazil has the biggest confederation of junior enterprises. There's a whole culture around this concept, people are really passionate about it. It may be an unexpected source of volunteers.

Today's meeting
We're using a shared document to make things more organized! This was really good addition to the daily notes. Benoît asked me to clarify a few points about I've written last week:


 * I expressed my interest in test some of the translations administration tools on What's next?. How I plan on doing it?

I wanted a page where I could experience how much time it takes to mark something to translation and other functionalities described on the documentation. It will be commons:Commons:Structured data/About. (Sandra, if you happen to read this, thank you for providing me that page!)


 * On the same subsection, I also mentioned how I wanted to make sure if everything that is on the Help namespace is marked for translation. He said he wasn't sure about if it's even possible to do it.

This was actually something I pointed out in my proposal named as "Inconsistency". One of the biggest pages I translated was Help:CirrusSearch. I noticed it refered to two pages that aren't marked for translation, Extension:CirrusSearch and Extension:CirrusSearch/CompletionSuggester, as "further reading".

I wonder how many pages referenced in documentation are actually only available in English (and I observed one of them is linked as Special:MyLanguage/[name of the page]) and how many important or useful pieces of information aren't accessible because of that.

I've come to the conclusion there are two ways to deal with this problem:
 * 1) Actually marking things for translation (it takes a ton of effort since we don't even know what to mark)
 * 2) Making solid recommendations about what to reference on documentation and how in the Manual of Style.

Honestly, #2 seems easier and it's a better long-term fix.

Building bridges
Of course, a way to find new volunteers is looking for people who are interested in the volunteering aspect of contributing to Wikimedia, so I searched for some organizations today. The main ones are Translators without Borders and The Rosetta Foundation. There's also PerMondo. But here's a problem: they are usually for occasional work, not continuous ones. Also, they usually have their own translation platforms. So even if a partnership is not completely out of question, I think it's more effective to talk to the volunteers themselves rather than through organizations.

I actually saw a lot of people commenting on their posts on social media talking about what languages they speak and their availability but... kind of clueless about how to begin contributing. There isn't a lack of translators but bridges between them and projects needing help.

This led me to ask if there are any initiatives that lists FLOSS projects to work on and which tasks need more help. One person talked about OpenHatch, that unfortunately has winded down this year, and their Recommended Projects list (Wikimedia is mentioned!). Another one mentioned GNU's page as a good resource.

Maybe we could improve meta:Meta:Babylon/Translations/New translators/Documentation adding suggestions of pages that need more translation efforts.

New sections
I decided to make important information more accessible creating two new sections so people don't necessarily need to read all my notes to find it.


 * will gather information about general problems I encountered as I read documentation and contributed as a translator.


 * Information about building strategies to find new contributors to translate the Help namespace pages will be on.

Reorganization of the documentation of my work
I've been thinking about restructuring User:Contraexemplo/Outreachy for a while (and yesterday's notes is a try on that), but I was also wondering if creating subpages would be too much so I was hesitant about it. I think I needed reassurance it wasn't a bad idea because as soon as I read a message from Benoît with the same suggestion, I decided to finally do it. I'm taking some inspiration from the way Wikibooks organizes books' chapters and organizing subpages according to its subjects.

Indirect outreach update
In Trip to next state, I wrote about how I ended up not meeting the coordinator of the Translation degree but got their contact information. They answered my e-mail and my first question: what are the minimal requirements of a certificate?

Minimal requirements of certificates

 * 1) Period of participation (i.e. from January 2018 to March 2018).
 * 2) Worked hours (i.e. 20 hours total, 3 hours a week).
 * 3) Activities perfomed (i.e. translation of documentation, revision of said translation).
 * 4) Issuer (i.e. Wikimedia Foundation).

I answered them asking some other questions:


 * What resources about best practices and translation of technical documentation you recommend?
 * Do you know any other groups, schools or organizations made of and for translators that might be interested in volunteer work?

I have some ideas for the "certificate problem", but I need to check some things first before writing them down.

Scheduled for today
Work on commons:Commons:Structured data/About.

Experience tagging Structured data/About, part I

 * 1) First difference: they use HTML to structure their headings, not the usual wiki markup. I wasn't able to identify how to tag the page name. Actually, I'm not even sure if it should be tagged. Should it? Documentation hasn't helped me with it, neither did a page already translated to other languages (commons:Commons:Structured data). By the way, there are some items of a list in it that aren't tagged for translation. I wonder if I should make that suggestion.
 * 2) How should I tag things like  ? See also is a template called when writing  . For instance, if a translator translates all of it , it probably won't call See also properly. Answer: Tag only what should be translatable.
 * 3) Most of pages aren't translatable yet. Should I include   on every link anyway since it will take you to the page in English regardless for now? Documentation recommends it for translatable pages only but could be a good practice to avoid reviewing the page source after referred pages are made translatable. Answer: that's definitely a good idea.
 * 4) I felt like it's quite difficult to predict how translation units will look without having Translation adminship privileges (and having access to the rest of the process).
 * 5) Weird behaviour: if I manually wrote the translation markers, it would detect it as a part of the text and not translation tags. If I used the shortcut, everything would work normally. Wondering whether it's intended behaviour or I did something wrong (on MediaWiki.org both ways work just fine).

I saved my changes on a external text editor. I'll publish them tomorrow after I check the documentation again and ask Benoît some questions about commons:Commons:Structured data/About particulatities I mentioned above.

Funnily enough, this page is now tagged for translation even though I only mentioned the translation tags as code examples. I'll figure this out tomorrow. Follow-up: Now that I deleted direct mentions to the translation tags, it isn't available to being marked.

Third bi-weekly report
The third bi-weekly report is due today. I'll be taking some time to write it, translate it to English and publish it.

Experience tagging Structured data/About, part II

 * 1) Updated Experience tagging Structured data/About, part I with some answers to my questions.
 * 2) Almost forgot to use  . Even though the same links were mentioned over and over again, I chose to give them different variable names.
 * 3) Since lists were quite long, I marked item by item individually, leaving the wiki markup outside the tagging.

Changes were submitted.