Page MenuHomePhabricator

Translation outreach: User guides on
Closed, ResolvedPublic


Profile Information

Name: Anna e só
IRC nickname on Freenode: contraexemplo
Mastodon profile: @Anna
GitHub profile: contraexemplo
Location (country or state): Brazil
Typical working hours (include your timezone):

  • Morning: From 08:00 to 12:00.
  • Afternoon: From 14:00 to 18:00.

Brazil has a daylight saving time from October 15, 2017 to February 17, 2018, so during that period of time my timezone will be UTC -2h. After February 17, 2018 it will be back to normal (UTC -3h).



According to Steve McConnell in his book "Code Complete: A Practical Handbook of Software Construction", "construction’s product, the source code, is often the only accurate description of the software". While this is true, in FOSS projects like the ones headed by Wikimedia — which rely heavily on voluntary collaboration —, the source code cannot be the only way of documentation. We have to keep in mind that contributions are made by people with different backgrounds and technical levels, so it's fundamental to have localized, clear and easily accessible user documentation.

Wikimedia's documentation

It's possible to observe the status of localization of Wikimedia's documentation in this page about it. Aside from English (since it is the source language), documentation is only 100% translated to two different languages: French and Polish. It is also 86% translated to Spanish and 71% translated to Italian, Lithuanian and Chinese. Other languages have less than 55% of work done.

Although English is somewhat an universal language for software, having all documentation only available in a few languages or only English is not compatible with one of Wikimedia values, "We welcome and cherish our differences" and with its mission, "to disseminate open knowledge effectively and globally". Providing accessibility to people in as many countries as possible can provide easier ways to present technical information to contributors while making them more qualified to make use of the software.

In the article "The Quality of Open Source Software", Tomi Taipaleenmäki and Teemu Törrö dedicate this subject a proper section. They state that "this lack of documentation can become a problem in the future, if the project evolves and gains success. Any new feature that is left without documentation can make the project more difficult for new developers to approach or users to comprehend how the new features work". They also say that "poorly done documentation effects also on how well new users can learn to use the application". Since documentation doesn't receive a lot of attention and frequently its localizated versions are not updated as much the source text is, according to T158296, this can disturb and/or mislead those who rely on it.


As I translated the pages indicated on T158564, I noticed that in long documentations like the one for CirrusSearch there are some problems like:

  • Comprehensibility: through the extension of the documentation, there were a lot of occasions I didn't actually comprehend what the person who wrote it was trying to say. The extensive use of commas and long phrases harms readability, lowering the quality of the subsequent translations.
  • Inconsistency: Documentation points to pages that can't be translated. Some examples: Extension:CirrusSearch and Extension:CirrusSearch/CompletionSuggester.

Even though analysis of documentation is not explicitly stated as a responsibility on T158296, I see it as an important step to understand why translations are not made and as a way to improve it since its existence is essential to Wikimedia. T121500 talks more about this (and other tasks related to it).


In "Is Documentation Holding Open Source Back?", Jack Herrington suggests that "if our intent is to encourage people to use these tools and to contribute their time to the development of these tools, we need to spend more energy on introductory documentation". Julien Danjou also states in a post called "The bad practice in FOSS projects management" that making people who aren't English native or fluent is also a flaw on FOSS projects. Those statements support the conclusion that Wikimedia needs to take proper care of its documentation before it's too late since the long-term effects of improper documentation maintenance can put the longevity of its projects in danger.

Main course of action

Finding new volunteers will be the main focus. Symptomatic issues and immediate solutions are easier to perceive when you expose new people to a new environment. What keep most people from helping out? What are their perception about Wikimedia and its projects? What would make them contribute? What can we do to attract new volunteers continuously?

According to Oded Nov in "What motivated wikipedians?", "user-generated content outlets that seek to recruit and retain volunteering content contributors, must focus their marketing, recruitment, and retention efforts on those motivations that are high in relative importance". The top tiers described on this article were Values ("opportunities to express values related to altruistic and humanitarian concerns for others"), Understanding ("opportunity to learn new things and exercise their knowledge, skills and abilities") and Enhancement ("opportunity for contributors to serve the ego and publicly exhibit their knowledge").

Social aspects ("chance to be with their friends or to engage in activities viewed favorably by important others") are also viewed as fundamental. In "Working for Free? Motivations for Participating in Open-Source Projects", Alexander Hars and Shaosong Ou demonstrate that "community identification" is the second internal motivation that leads to volunteering, only behind of self-determination. They describe this behaviour as "(....) a variant of altruism. It corresponds to Maslow's needs for belonging and love. Programmers may identify themselves as members of the open-source community and align their goals with those of the community. They may treat other members of the community as kin and thus be willing to do something that is beneficial for them but not for themselves." This indicates we should put some effort on building bridges between newcomers and people who are already wikimedians so they can feel this sense of belonging and feel motivated.

Possible mentor(s): @Johan and @Trizek-WMF.

Have you contacted your mentors already? Yes.


The proposed workflow is focused on continuous improvement using the Deming cycle as a reference (plan-do-check-act). It is flexible enough to be changed when needed and widely adaptable to embrace new challenges and plans. Constant feedback and immediate response are the keys.

<table> <tr> <th>Period</th> <th>Task</th> </tr> <tr> <td>December 5–12</td> <td>**Community bonding period**. Getting to know more about current tools, what has been done before, what is realistically possible to do considering limitations.</td> </tr> <tr> <td>December 13–22</td> <td>Discussion. Consulting notes done before. Reach out communities and other collaborative parties to ask them about difficulties and suggestions. Identifying problems, ranking and labeling them as "root" or "symptomatic". In parallel, strategy building takes place: writing down possible solutions, ranking them accordingly to possible effectiveness, labeling them as "long-term" or "immediate".</td> </tr> <tr> <td>December 25-January 1</td> <td>Holidays break.</td> </tr> <tr> <td>January 2-5</td> <td>Review the information collected on the Discussion phase and elect the strategies that will be used.</td> </tr> </tr> <tr> <td>January 08–February 09</td> <td>Initial outreach. Applying strategies described on previous task.</td> </tr> <tr> <td>February 12–13</td> <td>**Initial outreach evaluation and discussion**. What did work? What did not?</td> </tr> <tr> <td>February 14–March 05</td> <td>Continious outreach while also analysing results. Final evaluation.</td> </tr> </table>


  • I will make weekly reports about my findings which will be sent to my mentors when required, compiled as the timeline progresses and fully available at the end of the internship at any place of choice. I'm writing daily notes in this page.
  • I will be available at IRC in my working hours to collaborate with my mentors.
  • I will use Phabricator for managing subtasks and asking for help and suggestions.
  • I will be at reach through e-mail when needed.

About Me

Currently a mechanical engineering undergraduate. Passionate about technology, open-access and the free software movement. As a visually impaired person, one of my greatest motivations to pursue those things is to provide universal accessibility since I know how difficult it is to live in a inaccessible world.

How did you hear about this program?

I am always looking for new ways to engage with FOSS and general technology communities, so I was searching for any event that would take place at my city. This year, Goiânia hosted a meeting called 5º Encontro Nacional de Mulheres na Tecnologia. I read their schedule and saw a talk about internship opportunities that mentioned Outreachy. I couldn't go, but this brand new information stuck with me. So I eagerly waited since May to apply.

Will you have any other time commitments, such as school work, another job, planned vacation, etc, during the duration of the program?

  • As stated on my application on Outreachy's site, even though I am currently a undergrad my university break is between December and March. I have only one exam after the internship starts, but my professor is willing to anticipate it so it does not disturb my schedule.
  • My possible mentors mentioned they will take some time at the end of the year for the holidays so I'd like to do it as well between December 24th and January 1st.

We advise all candidates eligible for Google Summer of Code and Outreachy to apply for both programs. Are you planning to apply to both programs and, if so, with what organization(s)?

No. Even though I know how to code, I identify more with Outreachy's core values and goals.

What does making this project happen mean to you?

I fell in love with this project. Not only I want to gain experience so I can build a career but also because I admire Wikimedia's work and I share the same core-values. I've always pursued a way to make a difference in the world and I believe this is one of the most effective ways this could happen: providing open-knowledge side by side with amazing collaborators.

Outreachy's existence per se pushed me to get even more involved with FOSS communities. I was once afraid of contributing but finding projects filled with passion made me passionate as well, so I stopped worrying and started working. I see this internship as a way of thanking the people who make initiatives like these possible with my hard work and as a form to demonstrate that people like me — a disabled woman — can find their place in the technology field. I want to be the model I wanted to have when growing up.

Past Experience

I am a long time FOSS user but only began contributing to open-source projects in the last few months. This change was motivated by quitting Twitter and signing up to Mastodon, a free open-source microblogging platform for everyone. As I became more and more comfortable since the community is very welcoming, I felt a need of thanking those developers for building this amazing software in a time I didn't feel optimist about social media and the state of internet. I noticed how similar European Portuguese and Brazilian Portuguese translations were and I decided to localize Mastodon fully to my language:

This also motivated me to translate its landing page,

which was acknowledged by Mastodon's main developer, Eugen Rochko.

Those were the first times I've ever used GitHub and git and it helped me establish a workflow. Not only I've dealt directly with translation documentation but I've also led some tests thanks to it. Those tests involved installing and running a local instance, loading the right files, making some debugging and gathering information from those who used it. Once it was approved by me and my testers, I submitted a pull request that was later merged to the source code. To sum up, this is what I learned:

  • to organize my workflow;
  • to use git and GitHub;
  • to read and follow properly the official documentation;
  • to run a virtual machine with Ubuntu Server 16.04;
  • to install, run and maintain a Mastodon instance;
  • to manipulate YAML, erb and JSON files;
  • to do l10n work;
  • to run tests and gather information from testers.

I also helped to localize two of my favorite apps for Android:

And made some minor contributions to other things I use:

As for other experiences, I was enrolled in a course about software engineering for avionics for nearly two years (from 2015 to 2016). Not only I learned a lot about complex systems and documentation surrounding them but I also improved my communications and leadership skills as it was required to make projects as a team. I would say that was the first time I got interested in localization since in my free time I voluntarily (and unofficially) translated the documentation used in one project so my team mates could understand it better.


Other info

I will be writing about my experience with Outreachy and Wikimedia on Localizando-me.


  1. Steve McConnell's "Code Complete: A Practical Handbook of Software Construction". 2nd edition. Published by Microsoft Press in 2004.
  2. Tomi Taipaleenmäki & Teemu Törrö's "The Quality of Open Source Software", a seminar article presented on 2012 implementation of the Open Source Software Development course at University of Oulu.
  3. Jack Herrington's "Is Documentation Holding Open Source Back?", published in April 15, 2003.
  4. Julien Danjou's "The bad practice in FOSS projects management", published on his personal blog in June 09, 2016.
  5. Oded Nov's "What motivates wikipedians?". Published on Communications of the ACM, November 2007/Vol. 50, No. 11, pages 60-64.
  6. Alexander Hars and Shaosong Ou, "Working for Free? Motivations for Participating in Open-Source Projects". Published on : International Journal of Electronic Commerce, Vol. 6, No. 3, Communities in the Digital Economy (Spring, 2002), pp. 25-39.

Event Timeline

@Johan What do you think? Should I add anything else? Does the timeline look reasonable? :)

@contraexemplo hello! I see you have not answered the following question: "Will you have any other time commitments, such as school work, another job, planned vacation, etc, during the duration of the program?
" which was part of the application template in (Point number 9 under application process steps).

Could you confirm that "You will not be in school full-time for at least seven consecutive weeks between December 5, 2017 and March 5, 2018. School weeks include all weeks during a school semester and during an exams session, including short breaks and weekends. Full-time school means being enrolled in school during a semester when you are taking more than half of the credits a typical student takes". (as advised by Outreachy)

Deadline to submit application is in 7 days (i.e. October 23rd). Have you submitted your application also on the Outreachy website?

@srishakatux Hi! I updated my form to include this and other significant questions, thank you for pointing it out.

Yes, I submitted my application on the Outreachy website as well as all relevant documentation about my educational status.

@Johan @Trizek-WMF Hey, can you give me some feedback? The deadline is getting closer and I really appreciate your input. I've been making some significant changes since October 10 so I'd like to know if it sounds good enough.

@contraexemplo Two things that come to my mind:

Whereas your two main courses of action make perfect sense, comprehending the context in which Wikimedians work in a short period of time has historically proven difficult. I'm not saying it's a bad idea, but I think you can make more of a difference if you put more focus on the second part. Part of this is that we're already aware of some of the systemic problems and failures that come in the way of translatability, but changing the culture behind them is more difficult than pointing them out. Ways to engage interested translators who are not Wikimedians, to see translation as a way into the Wikimedia world, is something we know far less about.

Timeline: "Strategy building. Write down possible solutions, ranking them accordingly to possible effectiveness, labeling them as "long-term" or "immediate". Provide detailed description about how to apply those strategies" is planned for December 21 to January 2. This is over the holidays in western Europe, and the mentors live in France and Sweden, so there's a fair chance you'll get no or very little input during these weeks (and I imagine Brazil will have some holidays as well?). For whatever time you'd be working these dates, you should probably plan for something that'd require little feedback.

@Johan Thank you for your help. You have some good points. The outreach should focus on new volunteers, I'll make that more explict. However, I think that talking with wikimedians should still happen: in my experiences, I found it easier and better to contribute to projects in which I feel wecolmed and recognized for my work. None of these things can happen if there is little to no contact with the community. We need to build more bridges between newcomers and wikimedians.

What kind of activity do you suggest for this period? Maybe start building strategies while in the discussion phase, presenting than before December 22?

@contraexemplo Difficult, of course, as the order of doing things here makes sense. One thought that comes to mind would be to let the discussion and strategy building run more in parallell – start thinking more about strategy earlier, and keep building on it as the discussion goes on. And add a couple of days to that period, so that we could discuss it together (as it looks now, I plan to be back on January 2, for example). @Trizek-WMF, comments?

contraexemplo updated the task description. (Show Details)
contraexemplo updated the task description. (Show Details)
Trizek-WMF renamed this task from Proposal: Translation outreach: User guides on to Translation outreach: User guides on 6 2017, 6:01 PM

To any person interested in the findings of this Outreachy project: this page on contains links to my notes and reports. Happy reading!

Thank you @contraexemplo!

What is the final destination of this report? Any next steps? Do the community of translators know that it exists? It took me several clicks to find it, and I knew it existed.

It is too good to be forgotten or not acted upon!

@Qgil Hi! I haven't think of it, honestly. I've just landed in a new job in one of the partner software laboratories of the Ministry of Culture and didn't have much spare time lately. Do you have any suggestions of what I could do?

What is the final destination of this report? Any next steps? Do the community of translators know that it exists? It took me several clicks to find it, and I knew it existed.

@Johan, @Trizek-WMF : Any recommendations? For example posting to ? (Or anyone else in mind?)

Outreachy Round 15 ended in March 2018 and according to this project happened. :)
So I am closing this task as resolved. Potential followup items can be handled in separate tasks. Thanks for your work!