Anna writes

Thinking about FOSS, systemically

Thu, 17 Aug 2023 00:00:00 +0000

This is the script of the talk of the same name debuted at FOSSY 2023. I’m sharing it in full to allow those who didn’t attend the conference or won’t able to listen to any recordings to engage with this conversation.

Systemic. Do we understand what that word means?

Well, we, systems practitioners, start our journey by learning about something called General Systems Theory. General Systems Theory states that:

“Systems are a set of elements dynamically interrelated to perform activities aiming at achieving a specific goal, while consuming energy, materials or data (input) and producing new forms of energy, materials or data (output).” — L.V. Bertalanffy. General System Theory: Foundations, Development, Applications as cited by V. V. G. Neto, R. Araujo, R. P. dos Santos on New Challenges in the Social Web: Towards Systems- of-Information Systems Ecosystems.

This is the paradigm that is the guiding principle of systems thinking:

“Rather than reducing an entity to the properties of its parts or elements, systems theory focuses on the arrangement of and relations between the parts which connect them into a whole.” — F. Heylighen, C. Joslyn. What is Systems Theory?

The bigger picture.

Every minoritized person has at least a notion of what systems thinking is. It is, fundamentally, what allows so many of us to identify and fight to dismantle oppressive structures that exclude us.

I want to acknowledge first that systems thinking has been present in indigenous cultures and religions around the world—this isn’t a new concept. But it’s important to understand that General Systems Theory specifically—and, by extension, the academic definition of systems thinking—is proposed in opposition to what some authors may call reductionist thinking or conventional thinking.

Conventional thinking reduces a complex world to its parts. It assumes our world is stable, predictable, and objective.

On the other hand, systems thinking embraces how the world is uncertain, unstable, and experienced and understood from multiple worldviews.

I don’t want to give you the impression that conventional thinking isn’t useful—it can be! But human life is complex, and so are the things we build and the situations surrounding them. In fact, to some authors, the latter can be called messes.

In a continuum, you’ll find difficulty on one end and mess on the other. Difficulty would be the equivalent of a simpler problem and mess, of a complex situation.

Some authors say we can solve simpler problems, but we manage complex situations. We cope with them. Why is that?

Messes have more serious implications, multiple actors involved, intertwined and independent aspects and factors in different guises, and it often happens over a longer time-scale.

But most importantly, messes are hard to pin down. They’re hard to conceptualize.

Conventional thinking isn’t that great to cope with messes. Why?

We may ignore interconnections when we don’t look at the bigger picture.

We may assume the problem has a single cause instead of understanding that multiple intertwined factors may lead to that situation.

We may assume a single person is to blame instead of understanding how the situation that led to a problematic outcome came to be.

We may hyperfocus on an outcome—something we can measure—rather than on processes by which we can achieve beneficial change.

Let’s use what we learned so far to explore a complex problem within free software, starting with one worldview: I’m partially sighted. I was born with multiple bilateral colobomas. I used Linux distributions daily for more than a decade—until the accessibility tools I used started to fail. It got to a point I could barely read what was on a screen with what I had. No amount of Linux expertise I accumulated over the years could help me.

And I say deteriorating because, I really want to emphasize this, it used to be great! I can’t put into words how heartbreaking it feels to realize your favorite free software just became inaccessible. That brings us to factor number one: accessibility in accessible software can decline.

You can find multiple accounts written by people like me with details on why this is happening (I included one on my recommended reading). It has a lot to do with how we’re in the middle of a transitional moment—GTK3 to 4, Xorg to Wayland, and so on. That’s our second factor right there: transitions in underlying technologies.

One may think: well, if you’re so unhappy, just use something else. Many of us did just that—we ended up switching to proprietary OSes, which, I honestly hate. I’m actually using a proprietary OS right now to present this talk. But here’s the deal (and another factor to consider): working native accessibility tools are of no use if software isn’t accessible in the first place.

During my Human-Computer Interaction classes in college, the topic of accessibility was a footnote, not something extensively discussed and—most importantly—taught. It felt like it wasn’t treated as a requirement—even though there are legal implications and ramifications. Accessibility is seen as an extra feature, not a requirement.

That may be why not every developer knows how to develop accessible systems. And the developers who do know sometimes will move on to other opportunities, often not having someone to take their place. Accessibility as a specialty, not a commonality.

One could argue that this is a clear consequence of how prevalent the medical model of disability is in society. The medical model of disability perceives disability as a deviation from the “norm”. I have to conform the best way I can to this concept of normalcy to be treated like any other person.

But another worldview of disability is the one proposed by the social model of disability. It tells us my disability is a social experience—as in, it’s the result of an exclusionary society. With the right tools and accommodations, I’m just like any other person.

Those exclusionary factors are structural—and they’ve been here before we were even born. They all have social, economic, and political origins, repercussions, and implications.

They’re part of a reality that fails, harms, excludes, oppresses and kills marginalized people every single day. And this isn’t a separate reality from free software. Free software was built in this reality, it inherits and perpetuates its models, concepts, and power structures.

That’s why, as software freedom advocates, it’s our duty to question and dismantle them. How can we talk about freedom without liberation?

Systemic problems require systems thinking to promote true systemic change.

And it starts with you.

We need you to start thinking systemically. And we need you to never stop.

Now I promised you in the abstract of this talk that I would give you something, something you could hold on to to transform our spaces. As an academically inclined systems enthusiast, I need to be honest with you and say there’s a huge chunk of literature I just can’t cover here due to time constraints. But the chapter I’m using as my main reference for this talk, it tries to make sense of some of those things by talking about something they call purposeful intervention, of which the outcome is systemic change.

It is guided by three purposeful orientations:

Make sense of relationships between different entities associated with a complex situation. Understand in order to improve.

Surface and engage contrasting perspectives associated with this situation.

Explore and reconcile power relations, boundary issues, and potential conflict between entities and/or perspectives.

“Gently disrupt, unsettle, and thereby provoke new systems thinking.” — Martin Reynolds and Sue Holwell. Introducing Systems Approaches.

And that’s what I want to inspire in you. This is not an one and done conversation. This should be just the beginning.

Organize, intently.

Think, systemically.

Change, radically.

“A systems approach begins when first you see the world through the eyes of another.” — C. West Churchman as cited by Martin Reynolds and Sue Holwell in Introducing Systems Approaches.

A macOS survival guide

Thu, 08 Dec 2022 00:00:00 +0000

I switched from Linux to macOS 4 months ago at the time of writing. This is my first time using macOS, so I didn’t know a lot of things a more experience user may already know. A lot of my friends are making the same switch, so I decided to write a blog post compiling a couple of tips and tricks about macOS.

Setting up your machine

Enable FileVault. It’ll encrypt your startup disk.

Keep your recovery key somewhere safe. Several copies. You’ll need it to recover access to your disk’s contents if you forget you password and need to reset it with macOS Recovery.

You can also enable password resets via Apple ID. This option is turned off by default. Go to Users & Groups, click on the Show Detail icon and enable ‘Allow user to reset password using Apple ID’.

Consequences of resetting your password

You’ll have to log into your Apple ID account again.
If you want to keep using TouchID, you’ll have to register your fingerprints again.
If you use an Apple Watch to unlock your Mac, you’ll have to enable that option again.

Shortcuts you should know

You can find a complete list of Mac keyboard shortcuts here.

These are the three most important keys on macOS:

^: Control.
⌥: Option.
⌘: Command.

Clipboard management

Command + X: Cut.
Command + C: Copy.
Command + V: Paste.

Editing text files with nano

Control + O: Save your edits.
Control + X: Exit nano.

Window management

Command + Q: Quits an app. This will kill all processes related to that application. For example, if you have two Firefox windows opened and press Command + Q, that will close both windows.
Command + W: Closes an app window. This won’t kill processes related to that application, it will just close the currently active window. For example, if you just want to close one of two Firefox windows, you should click on the window you want to close and then press Command + W. This is also an useful shortcut to deal with Finder windows—Finder processes are so important to the functioning of macOS it will prevent you from killing them. If you’re hearing an annoying chime when you try to use Command + Q to close Finder, you may want to use Command + W instead.

Window decorations

macOS’ window decorations have three buttons: red, yellow, and green. Red closes a window (like the shortcut Command + W does). Yellow minimizes a window. Green opens an app in full screen—that will hide both the dock and the menu bar.

Deletion

Command + Delete: Deletes an item.

`Delete` versus `Forward Delete`

I’ve been programming my own mechanical keyboards for almost two years. Thanks to QMK, I’ve learned there are two kinds of Delete keys: one called Forward Delete (which is the Delete key you probably already know and love) and one simply called Delete (which works as both Backspace and Delete on macOS).

If I assign Forward Delete to a key using QMK, I’m not able to use that key for deletion shortcuts. Some keyboards work around this by having a physical and/or virtual Windows and Mac toggle. If the Delete key on your keyboard isn’t working as expected on macOS, macOS is probably treating it as Forward Delete.

If you need to use a macOS keyboard on Windows or vice-versa

Control = Ctrl
Command = Windows key
Option = Alt

Installing applications

You can install applications through the App Store or download external applications on websites like GitHub and GitLab. You should know that:

When naming package files, some people may refer to macOS as Darwin.
If you’re using a Mac with Apple SoCs (such as M1 or M2), you should prioritize downloading and installing applications developed for “Apple Silicon”. (Some people may refer to that as “ARM”, too, but make sure that app is compatible with macOS—there are thousands of other computers with ARM processors.)
If you find no mention of a “universal macOS” package or “Apple Silicion” package, don’t worry: you can run x86 applications on M-family Macs. You need to download and install a compatibility layer called Rosetta 2. macOS will prompt you to do so if you try to install x86 applications.
Applications for macOS are distribuited either as .pkg and .dmg.
- .pkg files usually guide you through a multi-window installation process just like Windows applications.
- .dmg files are macOS disk images. They create a virtual disk attached to your computer and usually open a window asking you to drag the application icon to the Applications folder (which results in an .app file). You can safely eject the virtual disk once you’re done with the installation process.
Some developers may not sign their applications. If you absolutely need to run an unsigned application, you’ll need to authorized it through a prompt on System Settings > Privacy.

System operations

You don’t necessarily need to shut down your computer every time you want to transport it. Macs using the M1 and M2 families of SoCs are so power efficient it’s okay to just put them to Sleep instead.
Annoyed by the startup sound? You can turn it off on System Settings > Sound.

Using an iPad with a Mac

You can use an iPad as an extended display with Sidecar (Tip: Connect your iPad to your Mac with a cable, otherwise the response times will annoy you). You can also control an iPad with the same keyboard and mouse you’re using with your Mac thanks to Universal Control.

Favorite applications

Homebrew: The package manager you’re missing so much after switching to macOS from Linux.
Hand Mirror: A menu bar application that creates a shortcut to your camera feed so you can check your appearence before meetings.
Hovrly: A menu bar application that helps you see what time it is in different timezones. Very useful for international teams!
Shottr: An advanced screenshot utility.
Dropover: A drag-and-drop assistant.
Rectangle: Window management. Offers Windows-like snap areas.

Daily planning and stand-ups

Thu, 03 Feb 2022 00:00:00 +0000

How we communicate

We currently use Zulip for synchronous and asynchronous communication. We have a private stream for organizers with two main topics we use daily: Stand-ups and Watercooler.

Our stand-up topic is where we post our stand-up messages every day (and nothing else). Sage and I have different post styles, but we came up with an emoji key that helps us understand at a glance levels of importance, urgency, statuses of tasks, and much more.

Our emoji key

🚧 - urgent WIP
🛠️ - less urgent WIP
✅ - done
ℹ️ - info, or another person completed this task
🔔 - pinged person who needs to do task
:date: - meeting
:mantelpiece_clock:️ - long term task
⏳ - urgent task that's coming up fast
:fire: - urgent and on fire
🏝️ - vacation
:cyclone: - mental health PTO
🤒 - sick day
:derelict_house:️ - old, neglected task
🏃 - time off (typically used for running errands)

Our Watercooler topic is where we talk about current and past tasks (synchronously and asynchronously) and how we’re doing. We frequently use it to communicate our time off.

My tools

I used to use jrnl to plan my day, but I decided to give Anytype (a really Notion-esque software) a chance after I received an invitation to their alpha program.

My system

I have a set of Daily Plan objects on Anytype where I keep all my stand-up files. Their names follow the YYYY-MM-DD format. I usually create the file for the following work day in my previous work day. I typically keep two things at the top of the file: a list of what I call Yesterday’s debt – all my pending tasks from the previous work day – and a list of noteworthy things to consolidate as documentation. They’re not shared in my daily stand-ups, but I often mention them in meetings.

I also started to maintain a section of blockers – things that are blocked on other people’s actions. I keep it at the top of the text I send every day in daily stand-ups.

With a list of tasks I need to complete at hand, I divide them in morning and afternoon tasks. My mornings are usually dedicated to tasks I need to complete before Sage starts their work day. My afternoon tasks, on the other hand, are tasks we can complete together in a working session or would benefit from having two people working on them at the same time.

/* Not shared in stand-ups */

[🔮 Yesterday's debt]

- Email X
- Discuss Y with Sage during our next 1:1
- Ping Z

[📝 Noteworthy]

- Communities A, B, C and D have a pattern of...
- Person E and F are...
- Intern G and H requested...

/* Shared in stand-ups */

[🛑 Blockers]
- 🔥 [Community] Intern R's extension
- 🚧 [Assignee] Contractor L's contract renewal

[🌅 Morning]
- 🔥 Review...
- 🚧 Ping...
- 🛠️ Revamp...
- ✅ Reply to...

[🌇 Afternoon]
- 📆 1:1 with Sage
- 📆 Onboard...

How to make Linux properly dectect your ZSA keyboard

Fri, 19 Mar 2021 00:00:00 +0000

TL;DR

The Moonlander Mark I and other ZSA keyboards can be flashed with a modified version of their firmware through a software called Wally. ZSA also offers a browser-based live training system on Oryx. However, neither work out-of-the-box on Linux – Wally needs a few dependencies related to GTK3 and libusb that may not be installed by default, and both Oryx and Wally need a new udev rule to properly detect ZSA keyboards.

The Moonlander Mark I and other ZSA keyboards can receive a modified version of their firmware through a software called Wally. That software sends a binary file generated by the Oryx configurator to the keyboard. Each reflash requires the following steps:

Compiling the desired layout on the Oryx configurator
Opening Wally on the command line or using its GUI
Following the steps on the screen (selecting the binary file, pressing the reset button, waiting for the firmware reflash to finish)

Oryx also offers a live training feature in Chrome-based browsers. However, both won’t work out-of-the-box on Linux – you have to install and change a few things before you can enjoy them.

Installing Wally’s dependencies on Linux

Wally needs dependencies related to libusb and, additionally, to GTK3 if you want to use its GUI. According to ZSA’s documentation, these are the packages needed on the most popular Linux distributions:

Arch family: gtk3 webkit2gtk libusb
Debian family: libusb-dev
RHEL family: gtk3 webkit2gtk3 libusb

Creating a `udev` rule for Wally and Oryx

Udev rules are created so events related to connected devices can be accessed without conceding unnecessary privileges to certain parts of the system.

To create a udev rule for Wally, create a file called 50-wally.rules on /etc/udev/rules.d/ using sudo.


sudo touch /etc/udev/rules.d/50-wally.rules

In that file, you should add the following lines:

# ErgoDox EZ
ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789B]?", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789A]?", ENV{MTP_NO_PROBE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789ABCD]?", MODE:="0666"
KERNEL=="ttyACM*", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789B]?", MODE:="0666"

# Moonlander e Planck EZ
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", \
    MODE:="0666", \
    SYMLINK+="stm32_dfu"

Finally, make sure your user is part of the plugdev group:


sudo groupadd plugdev


sudo usermod -aG plugdev $USER

Don’t forget to log out after making those changes so your system can detect and apply them!

Voilà! Your system is ready to use both Wally and Oryx live training.

References

Wally’s documentation on GitHub

Footnotes

If you use macOS, you also need to install libusb using brew:


brew install libusb

How did Open Collective's docs change in three months?

Wed, 27 Nov 2019 00:00:00 +0000

This is my last week as a Google Season of Docs technical writer and let me tell you, working with Open Collective was a delightful experience! In the last three months, I got to know more about one of the most fascinating communities in open source, worked with dedicated contributors, and — most importantly — I had the chance to improve all of Open Collective’s help pages as much as I could.

What’s new?

🆕 Open Collective’s docs now make use of the Group functionality. Our help documentation is now separated into nine sections: About, Product, Collectives, Financial Contributors, Expenses & Getting Paid, Fiscal Hosts, Contributing and Internal.

🆕 The Contributing section was added to help new and old contributors to understand better how to make contributions to Open Collective. It gathers contribution guidelines for Design, Development, Documentation and Translation.

🆕 Documentation now has contribution guidelines of its own, including a page of resources for documentarians, a style guide and a guide to teach contributors how to suggest changes.

🆕 Our repository’s main branch is now v2; master has been declared deprecated.

🆕 All key sections start with a page dedicated to frequently asked questions.

🛠️ Pages from all sections were updated to portray Open Collective’s most current interface. New media, such as GIFs, was added to demonstrate more complex actions.

🛠️ Outdated terminology such as backers and sponsors was replaced with current terminology. Names of key members of the Open Collective ecosystem (i.e. Financial Contributors, Organizations, Collectives) are now always capitalized.

🛠️ Our GitBook now has a content configuration file that tells the platform how to read our file tree and how to deal with redirects. This helps us avoid link rot, maintaining the integrity of our documentation.

The new version is already live! 🎉 Wondering how did it look like before and how much has it changed? The old version of our documentation can still be accessed on this page.

As a documentarian, my work isn’t limited to writing about how a certain product or process works — in fact, I would say that actual technical writing is only 10% of all the things I do.

My main goal is to understand the context in which those products and/or processes exist: the tools all members of the community use, the model of development, operations and delivery they chose to follow, how core and external contributors communicate with each other, how each new functionality is crafted, how every key member of their community interacts with both the platform and people around them. That’s why I invested a lot of time in understanding Open Collective as a whole. I connected with all teams and even had the chance to witness the release of new functionalities.

Our project in numbers

📝 Authored more than 120 commits on our documentation repository (and counting)

📨 Submitted 3 pull requests (#35, #36 and #39).

🤝 Attended 25 meetings

📋 Wrote 4 reports (including this one):

🙌 Closed 10 issues old and new:

🗨️ Left 4 unaddressed issues under the documentation label, including:

#2595: A new home for Open Collective’s documentation (please share your ideas and suggestions with us!)

That’s also the reason why the majority of my reports are about GitBook, our current documentation platform. I was able to work on our documentation both as an external contributor (through our GitHub mirror, submitting pull requests) and a core contributor (using GitBook’s web interface). I had to make some aggressive changes to our documentation’s structure, and those experiences helped me evaluate GitBook’s strengths and weakness and judge whether that’s still a good choice for our docs or not (my verdict: it isn’t).

What’s left to do?

🤝 Integrate better Open Collective’s aplication interface and our documentation
📹 Create more multimedia content about Open Collective
📧 Configure a changelog system (read more about it on issue #1674: Setup Changelog / Release Notes)
🏠 Find a new home for Open Collective’s documentation
🛠️ Improve our Contributing section
👐 Mentor new technical writers!

This community has welcomed me with open arms and I couldn’t be more grateful for that. Open Collective has found in me a contributor for life, and I hope to keep contributing for as long as I can. Thank you Google Season of Docs organizers, Open Collective and, in special, Alanna and Jaskirat.

Is GitBook the right tool for your organization?

Wed, 30 Oct 2019 00:00:00 +0000

As I mentioned in my last post, GitBook, once a popular CLI tool used by many projects and organizations such as Django Girls, became a closed source platform that offers free and paid plans to both individuals and teams to manage and publish documentation. Open Collective has been using it for a while, but its limitations started to disturb the documentation process as soon as I started pushing boundaries a bit in tasks like introducing a new organization of pages and groups of pages, or moving files to other folders.

My knowledge about GitBook comes from their (somewhat brief) documentation and weeks of trial and error. Worst of all, since I can’t be sure about how it treats my changes (and how they will interact with the current version of the documentation), a lot of those errors occurred in production (but were reverted as quickly as I created them, many of my modifications would break or remove a considerable amount of important pages).

What does it do well?

Uncomplicated set up

I have to give credit where it’s due, GitBook really offers an accessible solution for documentation. I know a few people who used it for more simple tasks such as publishing a book translated into Brazilian Portuguese and those are fantastic use cases.

Draft system

You are able to keep multiple drafts at the same time, and that can be a particularly interesting feature for organizations that have multiple people editing multiple pages at the same time.

Shortcodes

As a Hugo user, I really love shortcodes – they are a fantastic way of adding new functionalities (in special, visual or structural representation of some forms of content) without much work. It’s just a matter of creating a small HTML file, maybe adding a few lines to your CSS… And it’s pretty easy to reuse them in other projects.

While GitBook doesn’t let users add their own shortcodes, I believe the options they offer are sufficient for many of them: warnings, tips, notes, success messages, API requests, code blocks.

What could be better?

GitHub integration

My experience with GitBook indicates that it’s overly complicated (and a bit risky, even) to edit pages and the overall structure of the documentation through GitHub. Thus, contributions from those who don’t have access to the GitBook interface are limited to more simple tasks.

Releases

GitBook offers a Release feature to manage different versions of the documentation. They are controlled through branches on your integrated GitHub repository and overall, that feature works well… If your soon-to-be-deprecated version of your documentation isn’t still being changed a couple of times a week.

The platform assumes that your project isn’t a rolling release project, so it doesn’t offer a good way to solve conflicts between branches natively and keeping the current version up to date with the release candidate one is tricky.

What isn’t good about it?

Vague and/or incomplete documentation

I ran into a lot of trouble trying to merge my changes into our master branch; I broke our documentation several times in production and had no idea what caused such result. I also had no luck trying to reproduce that problem in another GitBook, and the platform doesn’t generate any logs whatsoever to help you diagnose such issues.

We had an incident with broken links while I was still investigating what happened with the missing pages that forced me to revert to the old page organization. I tried to write a post-mortem (issue #37) but I still don’t feel confident about what it; a few other incidents in the following weeks diminished my understanding of the platform and left me demoralized.

Lack of functionalities (that the old version used to have)

GitBook offers some integration with Google Analytics – it only provides the number of access each page had in total and nothing else.

Customization options are sparse, being limited to adding your logo to the website and choosing the colors of links and other discrete visual cues. You can’t even add your own custom CSS.

… And well, their Table of Contents implementation isn’t exactly what I would call great. I highlighted it just in case you don’t know where to look.

Zoomed out:

Mobile version or zoomed in:

Accessibility

For unknown reasons, GitBook developers decided to transform what is usually converted into alternative text in Markdown into captions.

This is what we usually add images in Markdown:

![This is the alternative text. It should be a description of the media you are embeding.](URL-or-relative-location.jpg)

This is what I expected:

<img src="URL-or-relative-location.jpg" alt="This is the alternative text. It should be a description of the media you are embeding.">

This is how GitBook treats images:

<figure data-key="076c11335091455ea2d9ebd605b1e7d1" class="reset-3c756112--figure-c0d4b308--figureWithCaption-408420be" contenteditable="false">
	<div class="reset-3c756112--figureAlignCenter-2d9bf702">
		<div class="reset-3c756112--figureLayer-b6ab7c94"></div><img tabindex="0" src="https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LWSZizTt4ZC1UNDV89f%2F-Lq6Q4e5r-N8oYhoKblR%2F-Lq6Q8M7tsgYQsQLXtk_%2FContributing_Documentation_Suggesting_changes_GitHub_Icon_Small_2019_09_16.png?generation=1569935109932465&amp;alt=media" class="imgTag-b489daf6" style="cursor: zoom-in;">
		</div>
	<div class="reset-3c756112--figureAlignCenter-2d9bf702">
	</div>
</figure>

And this is what it does to the alternative text:

<figcaption class="caption-8750cb6e">
<span class="text-4505230f--TextH400-3033861f--textContentFamily-49a318e1" style="max-width: 100%;">
Screenshot of our Welcome page. On the right side of the page, next to the title, there are two icons: one of the GitHub logo and another designating the Table of Contents.
</span>
</figcaption>

That’s honestly an awful decision – they could have added a caption feature without giving up on an accessibility feature. To quote WebAIM¹:

figure and figcaption allow a semantic association between a figure and the figure’s caption. The figcaption may provide a summary of or additional information about the figure and/or relate the figure back to the containing document. However, any image within a figure must still have an alt attribute value that presents the alternative text of the image - this should not be conveyed via the figcaption.

I got a bit distraught with this whole situation with GitBook because dealing with its limitations and unpredictable behavior took too much time of my main project – revamping the general help pages. It was so unsettling to constantly fight against a tool that is supposed to help me do my job my mentors and I started questioning whether Open Collective should keep using GitBook.

Well, should Open Collective adopt a new platform or software to manage their documentation?

GitBook’s shortcomings are hard to ignore, especially in addition to their now closed source and decreased amount of functionalities. I recognize that refusing to use proprietary software altogether would be a bit silly – there’s a significant amount of proprietary technologies that are too difficult or simply impossible to replace with open alternatives. GitBook, however, isn’t one of them.

Besides, as I wrote in my last post,

The most frustrating thing about GitBook is that its previous version was a lot more permissive and flexible than the current one – for instance, it allowed the use of third party plug-ins. They incorporated the most popular ones to their codebase to give them official support and that’s pretty cool, but their sudden change of heart makes a case for not depending on software or servers you can’t control.

Since GitBook uses Markdown files to generate our documentation, finding a substitute is a bit easier – there are a good amount of solutions which use Markdown – but not exactly trivial.

In my conversations with Alanna, she noted that core contributors would adjust just fine to any other tool; Open Collective’s documentation doesn’t rely on any specific feature GitBook offers.

I still have to talk to the Engineering team, but considering the tools Open Collective has used in the past, I believe that deploying it from their own servers isn’t mandatory. That means that we could probably use a lot of solutions that are completely integrated with services such as Netlify.

I have a few meetings with the team this week that will help me build a strategy to address all those issues, and I am particularly looking forward to the meeting with the Engineering team – we’ll discuss how to integrate the documentation process with the development of the application. I’m hoping that, by the time I take some time to write about my project again, I bring better news.

https://webaim.org/techniques/alttext/#figure ↩︎

My first impressions of GitBook

Wed, 02 Oct 2019 00:00:00 +0000

In two years working with open projects, I have used a couple of different platforms and/or frameworks to organize and manage documentation: MediaWiki, DokuWiki, GitHub and GitLab repositories, wikis and pages, Hugo, and finally, GitBook. But before diving in my experiences with GitBook, let me share with you my perception of the ones I’ve used the most.

Documentation platforms & tools I’m familiar with

MediaWiki

Developed for Wikipedia in 2002, MediaWiki is the software behind many of Wikimedia projects. Published under the license GPLv2+, MediaWiki was created to provide a highly collaborative and easily scalable platform using the wiki format. Available in 428 languages¹, it offers a version control system for each page, anonymous contributions (if enabled) and a multitude of tools thanks to its plug-in system.

While it’s a great software for the Wikimedia community and a few others such as Arch Linux, I would not recommend it for small to medium projects: setting it up can be difficult and often confusing; it has a steep learning curve; and projects of that size would probably benefit more from simpler platforms. If your team members and/or your community are familiar with wiki markup, however, it may be an interesting and flexible software to incorporate into your infrastructure.

Tainacan used MediaWiki to manage their documentation for a brief period of time – but as their team shrinked due to financial hardships, they decided to transfer their user and developer guides to Docsify. The amount of maintainance work MediaWiki requires wasn’t worth it for such a small team.

Pros

Maintained by the Wikimedia Foundation and the Wikimedia community
Supports a wide range of languages
Diverse plugin ecossystem
Works fantastically for bigger communities due to its scalability

Cons

Documentation is often confusing or lacking
Complex management system server-side and in the web platform
Overkill for small and medium communities

Resources

MediaWiki.org

This is one of the simpler approaches on that list. For some projects, a few Markdown files on a platform such as GitHub or GitLab are enough. Outreachy’s onboarding and internal documentation, for instance, is currently hosted on GitLab – and there is no need to change it the way it is. Those files are only accessed by a handful of people and each one of them is familiar with those platforms. Git tracks the history of our edits and we can use tools such as Pull Requests and Issues to suggest changes and have private discussions with a retrievable log. It’s also easy to add or remove collaborators, and if you don’t use self-hosted solutions, documentarians won’t have to create yet another account.

Pros

Simple, easy to set and manage
Git integration
Most popular platforms support a flavor of Markdown
Collaboration between team members and external contributors is easy to manage

Cons

Those who aren’t familiar with Git may need help understanding the platform and workflow
Too raw – repositories offer no customization and they can be quite user hostile

If you are looking for something more structured, both GitHub and GitLab offer built-in wikis. There aren’t customization options still, but navigation and separation between pages and sections of a documentation is a bit better. Oh my zsh wiki uses a GitHub wiki to guide their users.

Pros

More structured and user-friendly than repositories
Not too difficult to set up; you can add it to existing repositories in a few clicks

Cons

It also doesn’t offer any kind of customization; depending on your use, it can be quite limited

GitHub and GitLab also offer their own flavor of Pages, a feature that allows you to serve static websites hosted by them. You are able to use Jekyll, Gatsby, Hexo and many more.

This blog and my professional website are both deployed and served by GitLab Pages, and generated using Hugo. Kubernetes also uses Hugo to generate their website and their documentation.

Pros

Easier to use than solutions such as MediaWiki
Flexible and customizable

Cons

Many of them don’t offer a user-friendly interface to edit content – all contributors will have to either edit files on GitHub or locally on their computers

In between

No database – documentation containing thousands of pages may be difficult to manage with those systems, but smaller ones will find this a good thing

GitBook

GitBook used to be an open source CLI tool to generate documentation from Markdown files using Git. If you are familiar with the Django Girls tutorial, you have seen a good example what their tool was capable of creating.

Today, they are a platform that promises to help you build your documentation with both team members and external contributors in an easy way… And much of the spirit of their legacy tool was lost in that transition.

Open Collective’s contribution guide

One of my most important tasks in the last few weeks was revamping Open Collective’s contribution guide for documentation. It only taught potential contributors how to edit existing pages – important tasks such as adding new pages or adding media weren’t covered, and it didn’t explain much about what all those Git things are. It presumed external contributors had a certain level technical knowledge and it didn’t help much any potential contributors who didn’t.

Open Collective’s documentation also needed a style guide to consolidate all conventions their core contributors created: things like what terms documentarians should use to refer to certain functionalities and personas, writing style, media usage.

Working on those two pages made me realize that along with the Welcome page, the Suggesting changes and Style guide pages will always be a work in progress – and while there are some good reasons, others aren’t as good.

To write the Suggesting changes page, I had to work as an external contributor submitting changes through GitHub only – and GitBook’s integration with GitHub reminds me of the time I tried to play The Witness: just when I thought I cracked the code and truly understood the puzzle, the next challenge would prove me wrong. Worst of all, I can’t use other methods than trial and error to test my understanding of the platform and GitBook’s behavior can be so unpredictable at times there is no way to be completely sure I’m getting something right.

One of the most recent incidents was changing the organization of all pages through GitBook. On Open Collective’s GitBook, only a couple of changes seemed to be accepted by GitBook – others simply didn’t make it. To make things even weirder, when I created another GitBook with the exact same files, all of those changes were accepted without any issues. Exploring the administrative interface, I found out that GitBook did create all groups of pages I requested via GitHub, but for some unknown reason they weren’t being displayed. 🤷

Welcome page

We want to create a welcome page that will help readers to find the information they are looking for in a easy way. To do that, we need to understand how our users interact with our documentation: do they use the search bar? Do they have to click on many pages before finding the right answer? Does our traffic originates only from engine searches, our own application and our support channels or do our users know where to search for further information?

We can do surveys to answer those questions, but in our case analytics can also be a great evaluation tool. However, GitBook (1) only supports Google Analytics (a product we don’t want to use) and (2) it doesn’t do much with it. The only information you will get with Google Analytics integration is page views.

The most frustrating thing about GitBook is that its previous version was a lot more permissive and flexible than the current one – for instance, it allowed the use of third party plug-ins. They incorporated the most popular ones to their codebase to give them official support and that’s pretty cool, but their sudden change of heart makes a case for not depending on software or servers you can’t control.

Summing up

GitBook can be a great tool for core teams – it offers a WYSWYG editor, useful shortcodes, multiple draft support
However, external collaborators may struggle to contribute due to their limited, poorly documented and often buggy GitHub integration
GitBook doesn’t support any other analytics than Google’s – and it only offers a report on the amount of views each page had
Their Markdown to HTML implementation doesn’t follow the conventional format and, in certain occasions, it goes against W3C’s guidelines on accessibility

GitBook certainly has cool features, but it’s too easy to stumble upon its limitations – it’s just a matter of wanting to do something more.

Source: Article about MediaWiki on the Angolophone Wikipedia. ↩︎

Understanding Open Collective's documentation

Mon, 19 Aug 2019 00:00:00 +0000

As a documentarian, my work entails way more than just technical writing: it involves a systemic — not to be confused with systematic — analysis of the documentation taking into account the whole project. So whenever I start working on an open project, I ask myself the following questions:

What is the history of the documentation I am working with? On which platforms was it published?
How big is the documentation? How many pages are relevant to my work?
Which categorization method being used? Which personas (reader profiles) that documentation seeks to inform?
What is the writing style of the documentation? Is it consistent? Is a style guide available?

In this report, we will get to know a bit more about the current state of the documentation of Open Collective, the organization that welcomed me in this round of Google Season of Docs.

Open Collective is an online funding platform for open communities. It provides tools for raising and managing financial resources while making it easy to share their finances with their backers with great transparency.

Working open is one of my core principles and the source of my frustration with some open source communities — a frustration that inspired me to write the essay Open code! = working open. For this reason, when I saw Open Collective on the list of participating organizations, I had a feeling we were destined to work together.

Most links to external pages will take you directly to their archived versions on the Internet Archive to preserve the historical context of this report.

Historical review

Before being available under their own domain on GitBook ^[archived] , the Open Collective documentation was made available and edited on their GitHub wiki ^[archived] without many customization options and no page categorization. New sections were (and continue to be) created according to the demand received in communication channels such as email, Slack and their ticket system in Zendesk.

Having access to deprecated documentation when it has already been updated or moved is rare, but when it’s there, it’s a good a source for learning. For instance, there is almost no use of media such as images, GIFs, or videos on the wiki (and when there is, they are almost certainly broken because of the migration process they went through). There are also many pages in which the content revolves around references to external pages (like this section on widgets). This makes it quite noticeable that, along with a change in platform, there has been a positive change in documentation style and culture.

Mapping

From the GitHub wiki to GitBook, the documentation has gained a little over 60 additional pages and is now structured as follows:

Welcome
About
- Company
- Pricing
- Community Guidelines
- Team
- Investors
- Contributing
- Terminology
The Open Collective Way
- Values
- Community Guidelines
- Core Contributors Guidelines
- Core Contributors: Communication
- Core Contributors: Expenses
- Core Contributors: Leave
- Core Contributors: Compensation
Product
- Comparison
- User Profile
- Currencies
- Log-in System
Collectives
- Creating a Collective
- Quick Start Guide
- Edit Collection
- Add or Change Members
- Add Fiscal Host
- Change Fiscal Host
- Transparent Budget
- Expense Policy
- Approving Expenses
- Updates & Comms
- Tiers
- Goals
- Events
- Funding Options
- Data Export
- Buttons & Banners
- Integrations
- Zero Collective Balance
- Closing a Collective
Backers & Sponsors
- Sponsors FAQ
- Payments
- Collective to Collective donations
- Organizations
- Gift Cards
- Bulk Transfers
- Website Badge
- Sustainer Resources
Expenses & Getting Paid
- Submitting Expenses
- Expense Comments
- Edit an Expense
- Tax Information
Fiscal Hosts
- Becoming a Fiscal Host
- Create a Fiscal Host
- Fiscal Host Settings
- Payouts
- Host Dashboard
- Add Funds Manually
- Refunds
- Host Fees
- Local Tax Support
- Agreement Templates
- Open Source Collective
Developers
- Contribution Guide
- Best Practices Guidelines
- Bounties
- API
  - Members
  - Users / Emails
  - Collectives
  - Events
- README Integration
- Architecture
- Postgres Database
- PayPal
- Post-Donation Redirect
- Custom Tweets
- Manual Reporting
- Github Permissions
- Translations
- Testing with Cypress
- Collective’s location
Internal
- Team Retreats
- Brussels Summer Team Retreat
- Host Admin Manual
- Newsletter
- Support
- Issue Labels
- DNS Troubleshooting
- Developer Guidelines
- Architecture
- Testing
- Queries
  - Gift Cards
  - Transactions
  - Ops
  - Collectives
  - Hosts
  - Analytics
  - Emails
- Style Guide
Projects
- Maintainerati Berlin 2019
- Google Season of Docs 2019
Design
- Design Workflow
- Design Contribution Guidelines
Translators

Initial analysis

All sections are within the scope of my project (“Improve general help documentation”) in one way or another: culture-focused sections like The Open Collective Way and persona-focused sections like Collectives, Backers & Sponsors and Fiscal Hosts have a clear purpose to help users and deserve extra attention. On the other hand, sections like Developers, Internal and Design have relevant pages and need some structural modifications even though they aren’t a priority.

Note that the categorization of sections and related pages, as well as naming scheme, is not consistent. That’s an indication that they were created following different demands with multiple layouts in mind. There are also a small number of duplicate pages (such as Translators and Community Guidelines) and pages that can be merged into a single section of the documentation (pages under Developers, Design and About related to contributions to Open Collective as an open source project; pages under About and Product).

The homepage doesn’t help the reader understand right away which one of the personas covered by the documentation they are. Who are (or may be) core contributors, collectives, backers, sponsors, fiscal hosts? In the current setup, you need to visit each section to understand their roles — and some of these pages are hidden under sections with names that don’t indicate their theme effectively. Would you be able to guess that the pages about core contributors are under The Open Collective Way when other personas have their own sections?

The writing style is mainly conversational. The documentation addresses the reader directly several times (as in the answer "You've come to the right place!") and replicate possible questions (such as "Can I get a receipt for my donations?"). At times, the documentation also adopts an instructional language (like on the Edit Collectives page). However, there is no style guide for the Open Collective documentation.

Having all of that in mind, how should we proceed?

Methodological Roadmap

I will adopt the following script for the remaining days of the Community bonding period:

Detailed analysis of all pages
- What is the main subject of this page?
- Who is the page addressing?
- Is its tone conversational or instructional?
- Is there any media on this page?
  - If so, do they need to be updated?
  - If not, should we add some?
Identification of common themes between page groups
Proposal of a new structure
Submission for comments and suggestions
Presentation of the final restructuring plan

In addition, I will share ideas and findings in the #documentation channel on our Slack. If you are interested in following this discussion, feel free to join us!

MozFest is a reminder that the world can be a great place

Mon, 12 Nov 2018 00:00:00 +0000

Another day in June, another rant of mine about ableism on Mastodon. Except this time my words received a lot of praise, and I was sent an unexpected invitation from David Ross:

“Would you ever consider holding a session at MozFest? CFP currently open until August 1.”

At that time, I had less than a year of professional experience in tech - and my main source of income was my work as a documentarian in Tainacan, a public software being developed by the Laboratory of Participative Public Policies (L3P), based at MediaLab/UFG, in partnership with the Brazilian Ministry of Culture and the Brazilian Institute of Museums. The amount I earned could never pay me a trip to London even if I saved every penny for years. No problem, David insisted. He told me Mozilla has a travel stipend program to help people like me - who simply couldn’t afford such trip - and that I should really consider submitting a session. That was the first time I was actively invited to submit an activity to a tech conference, and I was honestly stunned. It was the kind of invitation I never received from any regional tech events I keep attending every year.

I submitted two sessions as the main facilitator and was included in another submission as a co-facilitator. I got so excited about the perspective of joining the Mozilla community I also applied to the sixth round of Mozilla Open Leaders. And, in the beginning of September, I received two emails: one telling me I was accepted for Mozilla Open Leaders, and another saying that Ephemeral, lost, forgotten - a session I submitted about the consequences of centralisation on efforts related to the preservation of culture -not only was claimed by the Decentralisation space but also granted me financial support to attend the festival on what would be the first international trip I would go in my life.

The Mozilla Festival Experience is absolutely different from every tech conference I ever attended - starting with the place where the event takes place every year: the Ravensbourne University.

Instead of closed and isolated classrooms, you find open spaces and a really inviting atmosphere at Ravensbourne. That, and the strong artistic vein of the conference encourages MozFest organizers and participants to experiment with decor and makes the festival visuals really fun.

The most interesting thing about Mozilla Festival, though, is how everyone can experience it differently. If you are more of a traditional talk kind of person, you can focus your attention on Dialogues & Debates, which features notable participants personally invited by Mozilla. If you want to explore every single space, there is always a different session taking place. If you just want to hang out in a single space, go ahead - no one will stop you. If you want to have just practical experiences, shed sessions are a perfect match. If you like to be directly involved in debates, learning forums will be your cup of tea. If you are overwhelmed, there’s a quiet space waiting for you. The event revolves around its participants, and makes a lot of effort to accommodate all needs.

My MozFest experience

My main goal was to meet and talk to as much people as possible, as well as let my curiosity guide me. Because of that, I only attended sessions. Here’s the ones I attended:

October 27

Is the Netflix of podcasts inevitable? (Decentralisation)

Unfortunately, due to the unfamiliarity with London public transportation, we arrived a bit late to this session, but still in time to join the debate about the advantages of offering a centralised and a decentralised solution to podcasts. I noticed a lot of the pros mentioned in favor of centralised platforms are about easiness to use, which is surely a challenge decentralisation initiatives have yet to overcome. Decentralisation solutions, though, seem to invoke a lot of expectations related to the democratisation of means of communication.

(Side note: I met Darius while participating in this session!)

![Photograph of Kayleigh Walsh introducing us to sociocracy. A nearby poster hooked in the ceiling shows a member from The Andromeda Initiative.](/2018-11-12-Sociocracy.jpeg)

I’ve been increasingly interested in studying systems of governance ever since I wrote an essay reflecting on my experiences as a Mastodon contributor. I had never heard about sociocracy before, so this session did a great job introducing me to that organizing all participants in two groups and giving us a project to work on to reach an agreement within the group. Here’s the workflow we used:

Appoint a chair and a “note taker” → Agree on a time boundary → Invite a proposal → Ask for clarifying questions → Open for quick reactions → Test for consent → Draw out concerns → Group them → Elaborate resolutions → Test for consent on each resolution → Redraft the proposal → Test for consent

I learned that it resonates a lot with my desire to build communities in harmonious and consent-based principles, especially as it uses equivalence and transparency to achieve effectiveness. It was one of those topics I’ll definitely spend the next weeks searching for all information I can find.

Defying our senses to promote diversity and inclusion in science communication with IGNITE (Decentralisation)

I met Gracielle Higino on Twitter after I became a Mozilla Open Leader and was amazed by how close we were without realizing! I got really curious about her session after learning more about IGNITE - that has a GitHub repository you should definitely check out -, so it was one of the first sessions I included in my schedule.

The participants and I listed in post-its all kinds of barriers that prevent the general public to access information - from language barriers (English-centered initiatives, use of jargons, people that speak too fast) to accessibility issues (such as heavy use of graphics and media without including resources such as audio description and closed captions, or the use of color palletes only to communicate a message, which may confuse colorblind people) and technical problems (websites that aren’t optimised for access on mobile phones and/or with limited data connections, searching for primary sources can be difficult or sometimes impossible thanks to the lack of citations and the amount of paywalls that limit the access on more prestigious papers).

We were then encouraged to use any tool on the table to solve those problems - and let me tell you, there was an unbelievable diversity of things to use, as you can see in the photographs Gracielle included in her post. In the end, we wrote down a few tips for scientists that wish to make their work more accessible - that went from adopting the open access philosophy to changing the way they communicate. It was a great session.

Design for Renaming (Privacy and Security)

This was an interesting session both as a person involved with Outreachy - a program that needs to be as accommodating and welcoming as possible, and has one of the most inclusive forms I have ever seen - and as a non-binary person that honestly don’t truly identify themselves with their legal name and currently uses a pseudonym in public works.

Participants were grouped in teams of three and asked to list situations where requesting “real names” or IDs- presuming it reflects the identity of someone accordingly- would provoke embarrassment, or even put their lives at risk by making them vulnerable to attacks of any sort. Then, we clustered those situations in common themes such as “financial” or “social” and proposed solutions to make more inclusive and ethical systems.

The facilitators, Emma and Cynthia, thoughtfully included content warnings and breaks to breathe to help people navigate the subject more safely. They deserve a lot of praise for facilitating a session in such a sensitive and welcoming way.

Unfortunately, I felt quite uncomfortable towards the end of this session as one participant in particular was insistent in pushing their ideas without any kind of input from the rest of the group. They kept disregarding what another participant, my partner and I suggested, protecting themselves behind the justification of “playing the devil’s advocate”. It was a bit jarring as this session happened in the Privacy and Security space, but didn’t spoil my overall experience - especially as Emma and Cynthia did respond to that indirectly in the end of their presentation, saying: ask only for absolutely necessary information.

(Note: another good thing about this session was finally getting an Outreachy sticker!)

October 28

We woke up with messages saying the Jubilee line was not operating properly that morning. This gave us a bit of time to eat our breakfast and enjoy the view from the restaurant.

Even with some reports of delays, we headed to the Southwark station and asked an employee about the status of the Jubilee line. They reassured us it was working with some minor delays, so we entered the station and just had to wait for a little while to get in the tube.

We were in London for a short amount of time so our views on their public transportation are truly anecdotal, especially as we didn’t use the tube in peak times, but we do find funny people complaining about how unreliable London public transportation is when delays in Brazilian cities are way more frequent. And as a person that lives in a city which public transportation relies on buses only, tubes will always be fast and comfortable enough.

The Hidden Fragility of the Internet (Web Literacy)

This session hit home as it addressed a subject relevant to what I have been researching in the last few months, so to me it was a pleasure to attend it. We had a lot of fun creating some web pages on paper as Clare explained some of the basic concepts behind her work. What would be a workshop aimed at people with more basic knowledge about the internet became a more casual conversation about ephemerality of content and preservation efforts while we prepared our pages to the link rot.

Talking about link rot, it was amazing to finally learn the name of that phenomenon that haunts my internet usage - and, as we discussed, a whole amount of public documents that reference a great amount of links that simply don’t exist anymore as they were at the time they were mentioned. I will surely follow the development of perma.cc closely - and, if possible, make some contributions.

Decentralized Web Standards: From ActivityPub to Webmention (Decentralisation)

![Photograph of Darius and Tantek facilitating this session. Tantek is explaining to us how Webmention works.](/2018-11-12-DecentralisationProtocols.jpeg)

As a person who translated Mastodon for a year and had to follow its development closely to properly guide users through the interface, the internals of the software were always subject to my curiosity. It stuck out as the first implementation of ActivityPub, and it still provokes debates on procedures, interpretations and interoperability. This session worked as a nice introduction to the most interesting documents to explore along to some basic concepts, especially as I feel that much of the current discussion around decentralisation is too technical and impenetrable to beginners like me. Here’s the list of documents they discussed a bit:

ActivityPub
Activity Streams
Activity Vocabulary (according to Darius, this one is the most interesting to look into first, as it will probably give you some good ideas!)
h-card
h-entry
h-feed
IndieAuth
microformats2
Micropub
Post Type Discovery
Webmention
WebSub
Microsub-speck

Ephemeral, lost, forgotten: how to help to preserve human history in an ever-changing world (Decentralisation)

Finally the session I facilitated! It brought together by far more people than I would ever expect, and I had a blast. At first, I was a bit nervous as my laptop absolutely refused any HDMI connection but as soon as a abandoned the idea of using slides to highlight important concepts and just carried on with a discussion about what kind of challenges historians from 100 years from now will face when trying to study our current way of life after my opening statements, everything went great. I noticed that sitting with the participants rather than being the only one standing up made them more comfortable to join the debate and explore their ideas. I would make rounds around the table to listen to them closely, and then add some spice to keep the discussion going. We talked about curation processes, the autonomy to tell your own story, the right to be forgotten, how hard it can be to understand the real context behind something… I wrapped up the session asking for them to write down one thing we should consider when preserving culture, and one thing we should be careful about.

![Photograph of myself smiling as show my partner the notes the participants of the session I facilitated wrote.](/2018-11-12-ResultsSession.jpeg)

Consider:

relationships
context
scope
people
individuality
horizon
the possibility of being remembered
the context in which it was created
the unattainability of true
emotional (empathy) state of author

Be careful about:

ownership
[being] inclusive
“completeness”
where’s it from
view point
filter
the right to be forgotten
readiness for different sets of problems
the unattainability of true
motives

Highlight: the Decentralisation space

As I stated before, my session belonged to the Decentralisation space - and that ended up being my favorite space of all. Their theme was Xenshana, an open world heavily inspired by afrofuturism, and that made the Decentralisation experience remarkable.

We were welcomed by Tendai, one of the Decentralisation space wranglers. She introduced us to the world of Xenshana, and invited us to join one of their four syndicates. My fiancé chose The Andromeda Initiative; I chose to join Mabwe Prima. We were handed cards with four questions about decentralisation, and encouraged to paint our hands with our syndicate markings.

![A character from my syndicate.](/2018-11-12-CardFront.jpeg) ![The four questions: How does someone go about building a decentralised community? What are the future trends for decentralised communities? How has your perception of community shifted over the course of MozFest? How can you implement the principles of decentralised communities in your life?](/2018-11-12-CardBack.jpeg)

After attending a couple of sessions, we would then come back and talk to one of the space wranglers. They would ask one of the questions in our cards, and if the answer satisfies them, we would receive a sticker, learn our secret greeting, and become a full syndicate member. A simple and ludic activity, but the perfect way to introduce people to the most fundamental principles of decentralisation and involve them in the story the space wanted to tell.

Acknowledgments

My time in London were some of the more intense and amazing days in my life. At the end of the festival, I was finally able to meet and hug David Ross (and thank him one more time for his words of encouragement!), and had a nice time talking to all the people he kindly introduced me to. In special, thanks Alicia for the nice chat in Portuguese! My partner and I enjoyed your company at the closing part a lot.

Thanks to all facilitators from the sessions I attended! We had some great conversations afterwards. Also, thanks to everyone that attended the session I facilitated! It was a nice surprise to see so many of you!

Thanks Darius for hanging out with us and being such a nice company! It was also a pleasure to meet and hang out with Emma!

Thanks to Ross Schulman for making me smile a lot when finally meeting each other, it was a pleasure to finally have a chat in person! Also, thanks to Tendai for being a sweetheart, exchanging experiences, being so excited about combining our efforts and having one of the most warm hugs I ever received.

During the trip, besides Gracielle, we also had the opportunity met Felipe (we caught the same flight to London and then back to São Paulo!), Geraldo, Cybelle and a lot of other people whom I don’t have their handles! Thank you for welcoming us, chatting with us and passing the time with us - and if you met us there, please reach out! I would love to continue our conversations.

Open code != working open

Tue, 04 Sep 2018 00:00:00 +0000

Mastodon is one of the most successful software solutions to the decentralized, federated social network called the Fediverse. Sp3r4z’s stats has some interesting numbers about it: there are 3,173 active Mastodon instances summing up 1,510,563 accounts¹. Using the motto “Social networking, back in your hands”, Eugen Rochko presents Mastodon as “a platform that is community-owned and ad-free”², that “aims to be a safer and more humane place”³. However, looking closely, the absence of encouragement to participate in Mastodon’s development in all promotional material produced, even though it’s becoming a famous free and open source software project, reveals an elephant in the room: a history of refusal to work open, and the idea that Mastodon isn’t a community-driven project that welcomes contributions – it is, in fact, considered to be a personal project by its creator.

“Look y’all here because I built Mastodon the way I wanted and you happened to like it. If you no longer like it that’s your own business, don’t give me shit about your failed expectations. There’s the door, there’s the code, there’s the alternatives. The shit I’ve received today just because I was open to something that a part of the community wanted is completely unacceptable.” – A toot written by Eugen Rochko in June 2, 2018 in response to the Trending Topics controversy

It’s time to talk about what happened in the Mastodon community – and, more importantly, how to avoid that such thing to happen in others.

About elephants and uphill battles

I left Twitter and entered the Fediverse one year ago. At first, it felt like paradise – I was welcomed by amazing communities and it was a place I could be queer and weird without any guilt. While Twitter felt like a never-ending competition for attention, engagement and audience retention – what usually led to outrages and more inflammatory content –, Mastodon was like a local gathering you could have heartfelt and sincere conversations without fearing hostility. Soon I felt the need to help it thrive somehow, and that resulted in my first contributions to a free software project.

But as I followed Mastodon’s development more closely, communication problems between the community and Eugen, especially when he expressed problematic opinions, started to catch my attention: for instance, his opinion on accessible design.

User: GIF autoplay? Why isn’t this opt-in, in order to make instances more accessible to people who need to avoid certain animations for health reasons? I really wish accessibility would be made more of a priority.

Eugen: Because you’re logged out. This is a setting when you’re logged in, but when you’re logged out, you obviously can’t customize anything. As to whether GIFs should default to autoplay in general, I think it is the expected behaviour that they do. That’s how it works on Tumblr, for example, and people create beautiful, captivating GIF sets. I think we want to highlight the fact that this is possible on Mastodon as well.

User: “Expected behavior” is why the internet is not very hospitable to people with disabilities. “That’s just the way the internet works” is kind of dismissive and unhelpful and sort of defeats the purpose of trying to be a better social network. I thought Mastodon was different… ?

Eugen: You are entitled to your own opinion on this, but just because I do not agree with you on this niche issue does not erase all the other ways in which Mastodon is different.

– Exchange on GIF autoplay on the pull request concerning the front page redesign⁴. It took him two days of discussions to accept the community’s position on this.

A similar debate happened when users urged him to implement an image description feature like Twitter’s. And while it eventually made it to the code base – not before a long debate about how it needed to offer more characters than 140 or how it doesn’t matter if people use it as a way to increase toots character count as the main benefit of this feature surpasses all of this –, its design felt like an afterthought and a lot of users still struggle to use it.

Since then, as Mastodon grew, I slowly realized that exhausting debates on important features to marginalized minorities started to become not the exception but the rule. Then it struck me – the community and Eugen weren’t working together to make a better software. We were in a constant uphill battle with a person who constantly promotes Mastodon as the ethical alternative to Twitter, to convince him to incorporate important aspects of software design to make it accessible and inclusive. That isn’t a partnership – it is a covert state of conflict.

“Queer activism has been the catalyst of change for Mastodon from the beginning, and many of it’s most defining features would never have come into existence without it. But Gargron refuses to acknowledge that, or change for transparency to allow for this to be a stronger influence, to allow for positive change. instead he whines about it publicly, pettily, and places the blame on the people who made Mastodon what it is now.” – Mastodon’s Complicated Relationship with Queer Activism, an excellent post by Hoodie, one of the most vocal Mastodon contributors from the early days

It didn’t took long until both sides engaged in an ugly altercation that would become known as the Trending Topics controversy. As Cass, a person who put a lot of effort to welcome newcomers to Mastodon for months, summed up in their post on why they left Mastodon:

Anyone against the idea and who understood how to use Github went to the issue list and objected there. They said that trending topics on Twitter is used to attract and abuse vulnerable people. It was all quite vague, but instead of asking for specific examples of abuse so that he could judge whether the software can prevent (or be made to prevent) abuse of members, Gargron dug his heels in. Then he made fun of the victims of social media abuse, making it clear that he doesn’t take their concerns seriously, while also complaining openly about people objecting vocally to his decisions and boosting toots by people publicly supporting him and condemning the wave of objection. He was petty and passive-aggressive. He complained that people were taking his words out of context and using them to attack him. That may be true, and if it is it’s unfair, but it’s also clear how he feels about the anti-abuse goals in the mission statement: he will only recognise abuse if it happens to him, because he is only building a social network for himself." – I left Mastodon yesterday

Stories about how a lot of people felt uncomfortable interacting with Eugen started to pop up – and I have some myself. A part of the community started working on ForkTogether, which was initiated by Mastodon’s former project manager, Maloki. And as we wait for a better alternative to appear, we ask ourselves: wasn’t Mastodon supposed to be better than this?

Working open

Mark Surman, executive director of the Mozilla Foundation, defines three principles as the foundation of open leadership:

Sharing decision-making, giving the community the power to shape the project and point it to a better direction.
Distribute content and code, as a way to encourage the community to maximize the “usefulness” of the project.
Inviting participation, welcoming people from different perspectives and making sure there are resources to help those interested in participate to join easily.

Unsurprisingly, Mastodon lacks both (1) and (3) – and that represents a severe risk to the longevity of the project.

Free software can’t solve the power imbalance between users and software makers alone by giving to the former the possibility to run, study, and distribute both original and modified copies. Such approach fails to acknowledge that the problems we face with proprietary software go beyond technological aspects, and that is possible to easily reproduce toxic patterns within open projects. Collaborative efforts take a lot more than just making the code available to anyone, being primarily based on human interactions and emotional labor. It takes:

Recognition. Volunteers pour a lot of hours and energy into their contributions because they feel they are gaining something out of that experience (improved skills or a more diverse network, for instance). And as most of them perform their duties in their spare time, contributing is a privilege that many people can’t afford. Their participation has to be encouraged, appreciated and credited. They should not be treated as an easy way to get quality work without any kind of payment for your own personal benefit.
Simple communication, as you need to include people from all kinds of backgrounds and technical levels. Never assume someone is in the same technical level as you – ask questions and follow through appropriately but without being condescending. Discourage the use of expressions such as “obviously”, “everybody knows”, “it’s pretty clear that…”.
Listening. Offering a platform they can discuss important aspects of the project isn’t enough when you don’t listen to their concerns and address them properly, acknowledge their contributions to debates. More importantly, recognize when your perspective is limited, take into account different points of view, and step back and apologize if you make a mistake.
Caring. Writing a Code of Conduct and actually enforcing it isn’t optional, and it isn’t trivial either. Don’t cut corners on this – the personal safety of community members need to be considered a priority. Have an incident response team, train each other to address the most common violations, write a script to make the response process as automatic as it can be.
Setting your project free. You should act as tomorrow was your last day at that project and make everything possible to make its existence not dependent on you. Delegate responsibilities, and document your work properly.

Having such a bad experience with Mastodon was painful, but meaningful. It shaped how I see open projects, it made clear to me that a diverse, engaged community can make all the difference in the world for the better – just as a “benevolent dictator” can have the opposite effect. And it made me realize that we can definitely do better than this.

Data collected on August 28, 2018 at 7:28 PM (UTC). ↩︎
Quotes taken from the project website, joinmastodon.org. ↩︎
Quote taken from his blog post “Learning from Twitter’s mistakes” ↩︎
Direct quotes taken from the referred pull request. Emphasis with italics are mine. ↩︎

Documenting is the key to thrive

Fri, 02 Mar 2018 00:00:00 +0000

It’s no secret I am a fairly new member of the Wikimedia movement. As you can see here, I only started contributing on September 11, 2017, encouraged by Outreachy’s application process. Since then, I made a total of 2,254 edits including translations, daily notes about my internship and production of small videos to illustrate my Translation quick guide. I was completely immersed in one single aspect of the movement—technical translations on MediaWiki.org—for three full months, and I am aware I still have a lot to learn.

But I believe there is no need of having a great amount of experience with Wikimedia projects to point out that recruiting volunteers and organizing work on Wikipedia and doing that on MediaWiki.org requires different strategies—actually, if there is something that this internship proved right, it’s that sometimes you need novices that don’t quite know what to expect to help you find the most obvious points of failure. It’s like that QA joke:

QA Engineer walks into a bar. Orders a beer. Orders 0 beers. Orders 999999999 beers. Orders a lizard. Orders -1 beers. Orders a sfdeljknesv.
— Bill Sempf (@sempf) September 23, 2014

It makes me think about a recurrent trend in the software developement world: calling users “idiots” if they don’t behave like we predict. I disagree with this kind of mindset completely ¹: if so many people are having difficulties, maybe the problem isn’t them but the design²³. We cannot build systems and processes hoping that people will magically understand what we had in mind while developing them. We need to make them crystal clear—with no distraction whatsoever—so we can retain the most of the intended audience without running into perfectly avoidable problems.

“The Wikimedia movement is a volunteer movement: we edit and translate (and to a fairly large degree, do technical development and technical documentation) in our spare time, but the roads to becoming a translator are difficult to find, and it’s difficult to get engaged in the movement as a translator rather than as a an editor who sooner or later ends up helping out with translation.” — T158296

Here is an interesting fact: the Wikimedia movement isn’t a group of people deeply involved with free and open-source software, but a organization deeply driven by open knowledge that happens to develop free and open-source software to support their operations (and has a small, dedicated community with ties with FOSS as a result). This is an important distiction I suspect that makes all the difference when thinking about recruiting efforts for technical translation.

I was discussing with my mentors about how difficult is to a person that is not familiar with the Wikimedia movement to contribute as a technical translator. In Bringing documentation to light⁴, I point out that translation efforts are unorganized on MediaWiki.org, which kind of reflect the overall work culture within the movement: take a task you would like to spend time on (after all, you are doing this in your spare time); try to complete it as well as you can; contact us in case you run into any problems. We have chapters, the Wikimedia Foundation, user groups, thematic organizations, but my impression is that those things are there to support the movement, and generally every member not deeply associated with them works (or is encouraged to work) independently.

Although this strategy may work well with Wikipedia⁵, it has some downsides: you end up with a set of unwritten rules and conventions that are not easy to catch and usually are passed from a person to another informally (as organizing them takes a lot of effort and it’s easy to forget about this kind of task when you wish to dedicate your time to things you consider more important). Let’s face it: most people don’t like to document their work. It’s a boring, repetitive task, often not as exciting as coding or editing. And the way the Wikimedia movement works brings another challenge to the equation: even if they do document their work somehow, the lack of solid guidelines to help them complete this task (style guide, indication of where to make it available, how to publicize it) could result in not-so-useful documentation. The dimension of the movement itself make it difficult to find this kind of information. As a result, information is extremely fragmented.

Therefore, it’s not surprising that some of the most engaged editors will end up as occasional translators sooner or later. They belong to a group that needs to be fundamentally familiar with the way the movement works, the software that supports the operations of every single project. They have this willingness to help the movement because they know how important is to make content available in multiple languages. But here is something that often happens with people like me and them, people that aren’t “actual translators” but have the required fluency to do this kind of task: we are inexperienced (especially if this is our first contribution in the free and open-source software world and we are in charge of this role alone!) and frequently we don’t put much thought in long-term consequences. We just want to get things done⁶.

That is, of course, a recipe for disaster. Maybe someday you will become busier and won’t have time to contribute to that specific project. Consequently, you probably won’t have time to explain to someone else all the work you’ve done and that will require them to make some guesses. It won’t take long until inconsistencies begin to appear, making users extremely confused—particularly if said project follows the trend of only getting bigger and bigger everyday as we speak.

With that, we finally get to the reasons why I was so adamant and persistent about the idea of translation teams. After all, this is what most of the FOSS projects do, and being FOSS is one of the most fundamental traits of MediaWiki.

So I tried to create a Brazilian Portuguese team with new contributors only. I made a call on Twitter, being absolutely direct: I need some people to help me with this over the course of the next two weeks. I’ll issue a certificate of participation for your help. I had a better response than with my attempts to publicize the role of technical translators: with this approach, three people contacted me, two created MediaWiki.org accounts, one followed through—and they said they did this because they have always wanted to be a volunteer translator, but never heard back from projects they attempt to make part of.

Another surprise was my fiancé offering his help. He is a Systems Information undergrad and always wanted to contribute to free and open-source projects, but never did. He usually practices his English with Duolingo, but was growing tired of it. He saw that as an opportunity to combine business with pleasure.

And it worked. Both of my teammates have different schedules and sometimes they can’t contribute as much as they want (and I was busy doing other things during this period, so it happened with me as well), but together we increased the translation rate of selected pages from 24% to 65%. I am really happy with this!

So as you read this, I already interviewed both of them about their experiences and I am writing my final report. As my internship ends on March 5 and this is my second-to-last bi-weekly report, my next one will probably address my thoughts, conclusions and recommendations to the Wikimedia community. But this doesn’t mean it’s the end of my blog—I would say it’s only the beginning of it. I certainly enjoyed writing that much again and I still—and will—have a lot of things to share.

Just to make clear: I am not saying the Wikimedia movement does that. It’s just a phrase I have heard a lot in programming classes and social platforms. ↩︎
Another reason this bothers me a lot is its ableist roots. ↩︎
There is an article called The myth of the stupid user that resonates with a lot of I think about this particular subject. ↩︎
This piece was published on the Wikimedia blog last week, by the way! Yay for me! ↩︎
With some reservations, I would say—it’s not unheard of people complaining about how difficult or cofusing is to begin contributing when you don’t know any Wikimedian/Wikipedian, and how unwelcome they feel. ↩︎
This is a mistake I regret making when translating Mastodon, especially because I ended up involved with the translation of other related projects (mobile apps, for instance). When this internship ends, I plan on talking to other Brazilian Portuguese translators to write down our conventions and style guide. ↩︎

Switching strategies and recalibrating expectations

Thu, 15 Feb 2018 16:07:59 -0300

“You’ve written “Sometimes it feels like this is a task beyond my limits.” That’s a feeling on exploration tasks: the more you scratch the surface, the more you have to handle. Sharing that feeling with coworkers or your manager is important, because they can help you to prioritize and focus on what is important.” — My mentor Benoît, on my February 12 notes

I’ve been feeling this immense amount of grief lately. As time went by during the initial outreach phase, I’ve come to realize how short my internship is to solve most, if not all, problems I’ve encountered that disturb the process of recruiting and welcoming new technical translators, and that haunts me. I am aware I will have the chance of addressing them in my final report, and my findings will be extremely useful for those involved with MediaWiki and the translation commmunity as a whole. But the failure to reach universities properly, the confirmation that outreach strategies need to be applied during long periods of time to have a chance of working combined with the little time I have left inevitably hang over every decision I make, making me feel pressured and immensely distressed.

I may be grieving for my internship. We’re close to its end, and it’s an understatement to say I appreciated this experience — it is a cathartic event in my life. It marks the beginning of my professional life in technology, after many years of only being a user; the start of the process of switching careers. Working full time has already established itself as a part of my routine so it’s strange to think everything will cease in a matter of weeks.

I may be grieving for the loss of I was before all of this happened as well. I am in the middle of the process of saying goodbye to a part of my life, a part of me that was my reality for years but now belongs to a past long gone. But hey, you are probably here to know what I have been doing, so let’s talk about work.

In this week’s meeting, Johan suggested that I could create a localization team with language or translation students. This strategy is interesting for a couple of reasons:

It demands only a few people to work.
It could help me confirm or dismiss the existence of points of failure in the process of becoming a translator on MediaWiki.org and/or translating the content of said wiki.
It could help me provide guidelines for the creation of teams dedicated to technical translations.
It would introduce selected university students, looking for especializing in language study or translation, to the role of technical translator in the Wikimedia movement.
It would help me understand factors decisive to the choice of continuing to contribute or cease all contributions as a technical translator.

So I decided to pursue it. While I dedicate part of my time to trying to find at least four people to compose a Brazilian Portuguese localization team, I am also working on improving the Translation quick guide and writing a Beginner’s Guide to help newcomers get familiar with other important concepts. And, as it will seem kind of uncommon having so many new users suddenly translating a lot of pages, I created a page about this under Project:PD help as suggested by Benoît.

Here’s hope this strategy brings us good results.

Some loose thoughts on commercial social networks

Thu, 01 Feb 2018 00:00:00 +0000

Note: this text is more of a vent than anything else. I still intend to write more seriously about my perception of the changes provoked by commercial social networks, but not today.

“The short-term, dopamine-driven feedback loops we’ve created are destroying how society works. No civil discourse, no cooperation; misinformation, mistruth.” — Chamath Palihapitiya, former Facebook executive

I would really like to start this text by talking about how I have not had a Facebook profile for years, but we all know this is not true. Despite my choice to delete my account, Mark Zuckerberg’s company never failed to find out who I am, how I live or with whom I interact. As a social network with the goal of collecting information with the highest level of fidelity to reality possible, it is well known that Facebook encourages the user to give them to their list of contacts and applies controversial policies such as the real name policy. So my exit in the end might have been more of a symbolic act than an effective action to get my data out of there.

My dissatisfaction with Facebook and so many other contemporary social networks, however, stems not only from their use of personal data but from major changes in the way we view the world, we measure our worth, interact with other users and connect with people.

For example, I’ve been using Twitter for almost 10 years - it’s possibly the social network I’ve used the most in my whole life. I remember…

… the implementation of retweets.
… that Michael Jackson’s death caused such a high number of hits that the Twitter was unavailable for several minutes. … the 2010 World Cup and the jokes with Galvão Bueno.
… a fun, spontaneous community. Being able to talk to people more easily, to a tweet away.
…. a timeline that displayed all the content of every person I followed, chronologically.

And it is with great sadness that I note that this no longer corresponds to the current reality.

I even feel melancholy when revisiting these memories because, when I was younger, I believed that these products were developed for the benefit of the users. I would get outraged when they would introduce new features that I had never asked for, and I was really vocal when unsatisfied. “This social network only successfully exists because of us,” I thought. “They need us to survive, so they need to hear us, right?”

Wrong.

Like I said, I’ve been using Twitter for almost ten years. I keep coming back, in spite of everything. Because…

… everyone is there. If I turn my back on Twitter, I’ll be distancing myself with multiple friendships, important people, precious contacts.
… I may be missing out on something. An important announcement, a professional opportunity, a news that will change the world.

Instagram, Facebook, Twitter, Whatsapp, LinkedIn: these products have already established themselves as references in our daily lives. We need to be seen. We need to be remembered. So, in the end, it is not they who need us - all of this, little by little, has become essential in our eyes.

So we accept to be measured and judged by metrics. We feel anxious about this, but there are still benefits, right? That funny joke, that unmissable controversy, that connection with that third-degree cousin we played with once in childhood and we’ll probably never have a conversation again, but if we have to, it’s within our reach. We allow them to choose what is most relevant to us. And even though it has frightening consequences…

In the age of online relationships that social media companies claim to facilitate in a positive way, this feels like unacceptable.
— Caryn Vainio (@Hellchick) December 18, 2017

… we let this pass. And, as we spend more time entertained in these mini worlds, we lose the connection with a more diverse universe.

To say that this is a barrier for me as an Outreachy intern is an understatement.

Choosing not to be part of these social networks means, to some degree, experiencing social isolation. Rather than being accessible through more universal media such as telephone or e-mail, people prioritize their attention to closed platforms. To reach them, you need to play by the rules of these commercial networks - and often, they will be invasive.

New Facebook functionality to confirm users’ identities. No selfie for them? No account for you.

And even if you compromise, there is no guarantee that you will have access to that audience. Organic reach is declining. You need to build a reputation, create a unique way to talk to the public, an incredible visual identity. Reaching a large number of people with scalable strategies consumes an unbelievable amount of time and energy, and there is little room for improvisation.

So this constant search for ways to reach people to do my job made me once again question many of my choices and opinions. Am I exaggerating all of this? Am I worrying about the wrong things? On one hand, this widespread reliance on commercial social networks makes me feel my existence slowly fade away every time I refuse to be a part of it, and it scares me. On the other hand, to what extent is it acceptable to ignore my discomfort for a social status that is increasingly difficult to achieve and which requires extensive maintenance?

Bringing documentation to light

Thu, 18 Jan 2018 00:00:00 +0000

To be honest, before becoming an Outreachy intern at the Wikimedia Foundation, I had never thought about many of the technical aspects of Wikimedia projects. Obviously the work isn’t completed with miracles and magic, but the full complexity and importance of all the work done behind the scenes did not occur to me until I got involved with one of the most important aspects of a free software project: documentation.

!["Saint Jerome", by Caravaggio. The painting depicts Saint Jerome, a Doctor of the Church in Roman Catholicism and a popular subject for painting, even for Caravaggio, who produced other paintings of Jerome in Meditation and engaged in writing. In this image, Jerome is reading intently, an outstretched arm resting with quill. It has been suggested that Jerome is depicted in the act of translating the Vulgate.](/CaravaggioSanGerolamo.jpg) Painting of Saint Jerome, patron saint of translators, by Caravaggio. (Public Domain/[Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Caravaggio_-_San_Gerolamo.jpg))

My role is dedicated to finding strategies to increase the number of people translating user guides. But before exploring possible ways to find new contributors, I needed to answer four questions:

What do we define as a user guide?
Is documentation well written?
Are we capable of welcoming new translators?
What is the current state of user guide translations?

While the answer for the first question might seem obvious for those extremely familiar with how wikis work, it was a source of confusion to me. As I searched for more information on subjects I was struggling with as a translator, I got lost very easily. I eventually ended up with multiple tabs of multiple wikis open, with little idea as to which one I ought to be relying on. But as I learned the conventions behind the organization of wikis, it became clear that what I was looking for was the pages under the Help namespace ¹.

As for the state of documentation, the first thing I did when studying MediaWiki’s was to look for their style guide. There are several ways to convey a message, and that’s why style guides are an essential tool when writing documentation: they provide guidelines which enforce consistency, setting standards to be followed, and quality references to be seeked. They are the ultimate expression of how the project communicates with people, and are therefore an important part of the brand identity. Consequently, the absence or incompleteness of a project’s style guide will have direct influence on how the readers’ perspective of it.

MediaWiki’s style guide is far from being perfect, especially as it relies too much on external references without highlighting which practices it considers the best. Unfortunately, this is a problem that is not confined solely to MediaWiki, as it shows up on other documentation like the Translation best practices. Writers end up without good and reliable resources to do their work, leading to difficulty in establishing a target audience and a proper style of writing. And users, especially new users, may face problems to understand new concepts and processes.

As a person new to the Wikimedia movement, I experienced first hand what is like to be an extremely confused and overwhelmed newcomer as I translated pages like CirrusSearch. It took me days to get used to the Translate extension workflow and weeks to understand the most basic concepts behind it. And as I learned more, I realized that my path to begin contributing with technical translations was extremely erratic and far from ideal.

The process to become a translator needs to be easy to follow and to understand. Tools and resources have to be presented briefly but effectively so newcomers are aware of where to find answers to their questions. I believe Meta:Babylon/Translations it’s the most recommended page to present to newcomers, but there should be also initiatives to improve it creating new or complementary forms of introduction and training as instructional videos. That way, we will welcome those who are new to the movement better.

Now, as much as I wish to make content available to all languages, it’s essential to focus our attention on those which are spoken by the most active communities. There is a substantial effort by Community Liaisons to provide support to those languages, including the creation of a list of active tech translators, so I used that as a reference to understand who we need to recruit.

My next step was to define a number of pages to analyze having in mind all 23 languages mentioned in the active tech translators list. As Help:Contents receives a significant amount of accesses² and is mentioned as the reference for those looking for help on MediaWiki, I decided to study it and all the pages mentioned in it as well³.

Language	Translation rate	Ranking	Views	Monthly average	Ranking
Arabic (ar)	15.85%	18	28,279	943	7
Catalan (ca)	83.18%	2	18,078	603	16
Czech (cs)	32.40%	14	20,238	675	13
German (de)	67.30%	9	63,877	2,129	2
Greek (el)	16.25%	17	3,143	105	23
Spanish (es)	59.78%	10	34,641	1,155	5
Persian (fa)	15.13%	21	20,199	673	14
Finnish (fi)	15.15%	20	18,278	610	15
French (fr)	73.78%	5	35,035	1,168	4
Hebrew (he)	27.63%	15	17,259	575	19
Hungarian (hu)	12.15%	22	18,885	596	17
Italian (it)	36.00%	13	21,373	712	11
Japanese (ja)	68.53%	8	31,117	1,037	6
Korean (ko)	46.25%	12	24,997	833	8
Dutch (nl)	20.88%	16	20,976	699	12
Polish (pl)	70.83%	6	22,829	761	9
Portuguese (pt)	74.73%	4	17,782	593	18
Portuguese (pt-br)	82.25%	3	21,893	730	10
Russian (ru)	70.30%	7	43,302	1,443	3
Swedish (sv)	8.33%	23	5,915	197	22
Turkish (tr)	15.63%	19	17,187	573	21
Ukranian (uk)	56.28%	11	17,249	575	19
Chinese (zh)	86.53%	1	69,192	2,306	1

Chinese, Catalan, Brazilian Portuguese, and European, French and Polish are the languages with the highest translation rate on mediawiki.org. However, of these six languages, only two (Chinese and French) are featured in similar positions in the ranking by average views in a month, and only four (Chinese, French, Brazilian Portuguese and Polish) are among the ten most accessed languages. On the other hand, Swedish, Hungarian, Persian, Finnish, Turkish and Arabic are the languages with the lowest translation rates. Swedish and Turkish positions are similar in both rankings. However, surprisingly, the positions of the other languages in the completion ranking and the pageviews ranking differ from lot, especially the Help: Contents page in Arabic, which is the seventh language with the most accesses.

To understand the reasons behind those numbers is not just a matter of comparing number of pageviews and translation rates; it is necessary to consider social aspects such as the proficiency in English of the speakers of those languages. Consider the EF EPI index as a reference: countries like Netherlands, Sweden, Finland, Germany, Poland, Hungary, Czech Republic and Portugal have “very high” or “high” proficiency rates. Greece, Argentina, Spain. Hong Kong, South Korea, France and Italy have “moderate” proficiency levels. And China, Japan, Russia, Taiwan, countless Latin American countries like Brazil and Colombia, Iran, Afghanistan and Qatar are among those with “low” or “very low” proficiency. This helps to explain, for example, why there is such a high demand for documentation in Arabic even though the translation rate is one of the lowest.

Other important factors are the possibility of access to Wikimedia projects (which is more difficult in countries like Turkey, recognition level of Wikimedia projects in several countries (as evidenced by the Inspire campaigns and the organization of the communities in question.

Still, while being as large as the Wikimedia Foundation and its projects comes with a set of downsides, it also comes with a good amount of advantages. Wikimedia projects are consolidated as a reference in open knowledge and are admired by thousands of people. Those who read and those who contribute believe in our values and quality of work, so the most sensible thing to do to improve the current state of translations in user guides is to ask for their help.

Translation teams usually have a small amount of people, and this works in our favor as it’s possible to make a lot of progress with few contributors. And while it’s viable to find technical translators among people who already contribute to other Wikimedia or free and open-source projects, it’s also beneficial to the Wikimedia movement and MediaWiki to look for new volunteers. After all, most of contributors already dedicate their free time to specific projects. Although I am sure some would love to find room to help (and they are welcome!), this can become overwhelming quickly.

So, to find new translators, we need to look for places where diversity is welcomed and open knowledge is valued. We also need people that speak their native language well and also understand English at, at least, an intermediate level. Because of that, reaching out to university students and professors is our best bet, given this kind of collaboration has been growing in the last few years.

Talking to professors, especially those who dedicate their studies to fields as linguistics and translation, can be a valuable source of knowledge and the beginning of a partnership with universities to help us develop, for instance, a fitting set of best translation practices for MediaWiki. This is, moreover, one of the subjects of a conversation I am having with a professor involved with the coordination of the Translation course of the Federal University of Uberlândia (UFU).

As for students, there are multiple reasons I suspect they would be wonderful contributors. While they are encouraged to learn English throughout their time in the university due to professional demands, there are little to no opportunities to make use of the knowledge they have gained outside their classrooms. In addition to that, they are stimulated to look for different but relevant extracurricular activities to perform, but most of them can’t be done from the comfort of their home.

Technical translations provide them a chance to put their fluency to a test while improving their vocabulary and reading comprehension. Translating documentation is also a great and easy way to begin contributing to Wikimedia projects, as the Translation extension offers translators an easy-paced workflow and you learn more about organizational nuances and technical details the more you translate.

Therefore, in recent weeks I have explored two fronts of work: communication with professors and others involved with university administration, publicizing the role of technical translator as an interesting extracurricular activity for students, and direct dialogue with said students, making use of promotional materials making use of the relationship between Wikipedia and MediaWiki, and directing them to a shorter version of the Translate extension user documentation. The search for these two groups is done in three ways: direct but virtually through direct communication through emails or messages on social networks such as Twitter; in person, in meetings with coordinators of language schools or undergraduate courses; indirectly through the dissemination of promotional material made by volunteer students at various universities. The test of this strategy has been done locally in my country of residence: Brazil.

There are points of failure in the whole technical translation process—that goes from the quality of the source text to the lack of a strong translation community—and the path to finally solve them is long. MediaWiki needs to look up to good examples of documentation practices, like Atlassian or Write the Docs and establish and enforce a set of good practices for its documentation. It also needs to improve its localization practices, looking up to examples as Mozilla Firefox and improving resources made for technical translators. Providing a better training, making available tutorials more based on videos or other visual resources and less on text, is a better way to introduce newcomers to the tools they will use. Simple but effective introductions, like the one provided on Meta:Babylon, are also essential and need to be more publicized. Lastly, building bridges between those who are already long-time contributors and those new to the movement is a must. While you can contact other translators through the translators mailing list, it is still a way of contact with a great amount of limitations. It isn’t a proper place to have real-time discussions and email is becoming a less used mean of communication. Promoting the establishment teams for each language, encouraging them to create and organize their own conventions for recurrent translations and writing style, and electing volunteers among them to communicate directly with newcomers will provide all of them a sense of belonging and support.

That said, the legacy of 16 years of MediaWiki development, including all the user guides available at the moment, is still relevant, useful and needs recognition as much as it needs attention. And that’s because when you dedicate a few hours of your month to translate documentation into your native language that covers important aspects of MediaWiki as editing, you still help us give users access to tools to enhance their contributions and you provide them a better understanding of the interfaces they use. And while this helps to increase the quality of the content created, the chances of enhancing the software are also higher - more conscious users generate better reports on problems they faced, improving communication between them and developers.

Pages inside wikis using the MediaWiki software can be organized by namespaces to differentiate them by purpose. ↩︎
Wikimedia Foundation provides a tool available for everyone with which you can access data about pageviews in various periods of time. The earliest date is January 7, 2015. ↩︎
Data collected from January 5 to 8, 2018. ↩︎

Talking about the fear of failure

Wed, 10 Jan 2018 00:00:00 +0000

Before we go any further and talk about my strategies to bring more attention to technical translation in Wikimedia projects, I need to touch on a subject that most likely affects every human being: the fear of failure. As I wrote on January 2 in my daily notes, a few days ago I was filled with apprehension and uneasiness as I began to feel the burden of my responsibility as an Outreachy intern and to question how much room for failure I have. Although anxious to put my knowledge and learning into practice, I feared making mistakes and not achieving the expected success. What happens if I do not find the perfect solution, if all my ideas are unsuccessful?

I expressed my fears and insecurities to Johan and Benoît at our last meeting and they, being the good mentors they are, reminded me of several important aspects of the nature of my project and of a professional life as a whole:

This project is not like the others

While defining expected results for projects involving the implementation of a particular functionality in a software is an easy process, for one who proposes to find new strategies for recruiting new contributors this is somewhat more complicated. It is unfair to expect that I will solve all problems related to technical translation on Wikimedia Foundation in three months of action, and it is unrealistic to expect that the courses of action I propose will work out to the point where we can set goals in terms of numbers of new translators and increases in the percentage of documentation translated into each language. This leads us to the second point:

This is a research-focused project

And as in any other research elsewhere, results that are considered “negative” remain good results given the possibility of learning both with failures and successes. That is why, in addition to wanting to write a final report on my experiences, impressions and recommendations, I try to document my work as much as I can - thus, it is possible to better understand the paths that led me to those conclusions.

There is not such a thing as a “perfect decision”

When our plans fail, we tend to think that the other options we had at the time of decision could have led us to success. And while it is natural to reevaluate our deliberation process, it is unhealthy to be obsessed with the fantasy of possibility. The decision we make at one point is often the best we can do. We act taking into account the information available and our best judgment at the time.

“You could, for example, get hit by a bus if you had chosen something else,” Johan told me. This may seem cynical and overly absurd, but it is a very appropriate statement. There is nothing, absolutely nothing, to assure you that the other options would have been better choices.

Being flexible is necessary

Making a decision does not necessarily mean becoming devoted to it. It’s a good idea to set up a evaluation routine to check if you’re headed in the right direction to achieve your goals, and there’s nothing wrong with reconsidering other options even if you’ve invested a lot of time. In software development, this is one of the central points of the so-called (and extensively used) agile methodology.

Once again, it is important to note that testing options and recognizing that they are flawed does not mean wasting time and resources. Every action is an opportunity for learning and the result will always be to become a more conscious, experienced and wise person.

The responsibility is shared

I am not alone - my mentors and I are a team. We take action only after we have dialogued with each other and reached a consensus. If I do not agree to something, I am free to express my point of view and counter-arguments. If my ideas have no foundation or are something that has already been done and failed, they will let me know.

This attitude ends up creating a support network. It is not expected of me that I carry the weight of decisions (and their consequences) on my own. “We got your back, don’t worry”, they both said to me.

As a person who has been watching the technology world dehumanize those who work in the area with absurd working hours and deadlines, the possibility of being honest about my feelings and conflicts with the people who are mentoring me is certainly one of the most important aspects of the experience I’m having in this internship.

The process of growing — or, even better, flourishing — involves much more than having opportunities to put your skills into practice or people who believe in what you can offer. It requires, above all, a great understanding of human nature and an immense respect for its limits. And it is heartening to experience all of this while working with the Wikimedia Foundation.

I see things from a different point of view

Fri, 22 Dec 2017 00:00:00 +0000

For a long time, hearing the word “work” would cause me to panic. How would be my routine? Would my employer be capable of understand and provide the accommodations I need to execute my duties? Would I be capable of working or having attractive qualifications to be hired?

My experiences with (in)accessibility in my student life filled me with fear of the labor market. I only had access to assistive technologies in the beginning of my adulthood, in higher education, although my visual impairements are congenital. How much precious time have I lost trying to have access to the minimum while people without any disabilities had access to the maximum? If educators could not understand the necessity of adaptations, how would employers?

“According to the survey, 62% of workers with disabilities said they have encountered problems. Of this percentage, the majority complained about the lack of opportunities (66%). Following are: low wages (40%), absence of a career plan (38%) and lack of accessibility (16%).” — G1: “Professional with disabilities faces difficulties in employment, says survey”. August 18, 2016.

I am aware I have multiple privileges: I am a white, cis, lower middle class person. I had the opportunity of studying in good schools and I probably have more access to information than the majority of the world population. The fact that I can choose when to start working is already an advantage. The problem is, all of that cannot subvert the ableist logic under which the world was built.

The model of disability that is widely accepted and used by society is the medical one. In it, there are three fundamental concepts: impairment, disability and handicap.

Impairment is the result of loss or anormality of physical structures, fisiological, anatomic and/or psychological functions. It can be permanent or temporary.

Disability is the restricted perfomance or non-performance of certain activity as expected for “normal human beings”, and it’s a consequence of being impaired.

Handicap is the social consequence of impairment and disability: limitation or impediment of performing as expected socially and culturally like people without disabilities.

There are various problems with this approach: What should I do while my vision is a “normality deviation”? How will I live? Should I lock myself home until a cure or other medical intervention is discovered? And what happens if this never happens while I am alive?

“The Basic Education Census of 2016 shows that the participation of students with disabilities falls at each stage. In the initial years of primary education (1st to 5th year), 3% have some disability - physical and/or intellectual. At the end of the school year, this rate drops to 0.9% (…) The difficulties at all stages are mainly due to the lack of staff training and infrastructure.” — Estadão: Despite inclusion efforts, students with disabilities progress less. April 17, 2017.

The Social Model of Disability emerged as a way of opposing medical ideas. Its premise: disability is a situation, not a condition. It is experienced in circumstances where accessibility - a form of inclusion completely based on the independence of the disabled - does not exist. Therefore, the origin of problems is not attributed to the individual that is a “normality deviation”, but to the way society was shaped.

Although the social model is accepted by most organizations and today is the basis of some legislation, the path and fight for its widespread adoption is still long. Because of that, it didn’t take long until my euphoria for the internship was replaced by fear. How many people with disabilities have gone through Outreachy? Will I perform well working remotely?

Preparation

As soon as I received an e-mail from Outreachy organization with the first intructions I contacted my mentors to decide how we would communicate with each other. We decided to have a videoconference per week on Mondays for discussions about lastest findings and next steps and written communication through a chat for quick questions as they receive a large stream of emails.

One week before the official start of the internship we had our first meeting. I was extremely nervous since I am used with only writing in English, but this soon turned out to be an unfounded concern: both Johan and Benoît are not Americans and English natives, which makes our conversations easier to understand since we all talk a little slower. We discussed expectations, what I want to learn from the internship and the problems I noticed during my two months of experience as a translator on Wikimedia Foundation projects.

In these conversations, I realized the importance of being a new contributor to Wikimedia projects. My two mentors have more than a decade of experience and contributions, so the organization’s operation and the structure of its projects are extremely familiar. While this is a key factor in their role as community liaisons, such baggage may become a disadvantage when it comes to identifying problems that makes the inflow of new contributors difficult. In my attempts to understand the emergence, growth and establishment of voluntary contributions and movements, in addition to the functioning of the contribution process, I end up exposing previously imperceptible points. It is not uncommon for me to hear the phrases “I had never thought of this approach before” or “I had never noticed this problem.”

Since my work mainly involves research and analysis, making progress less noticeable than in an internship where you produce lines of code, I have decided to document thoughts, ideas, and discoveries on a dedicated subpage of my user page. Besides being a useful tool to keep me aware of the work I’ve done and to point out new directions to explore, it makes the progress of my internship accessible not only to my mentors but also to anyone who is interested. Another very useful instrument is a document shared between myself, Johan and Benoît to facilitate the construction of guide for videoconferences and access to requests or questions that can not be addressed instantly.

That way, we have developed a process of constant feedback and improvement. This gives both parties the security of a job well done.

Experience

If I was afraid of the work routine before, today I am afraid of not finding a job as enriching as this internship. My daily routine is guided by my curiosity and willingness to learn, and my mentors are constantly looking for new opportunities for me to grow. There is an immense respect for my independence and space for me to take whatever actions I deem necessary and pertinent. It’s also not uncommon to hear “I do not want to influence you,” “you’re free to put my suggestions into practice or not” or even “if you find there are too many problems to recruit new volunteers, no problem, we understand”.

The focus is not the possible end result - the presence of new volunteers to translate documentation - but the intense search for translation strategies, and this involves many processes and aspects beyond user contributions.

As a disabled person, this has been a unique experience. Remote work, done in a virtual environment, and flexible hours allow me to adopt the pace that I feel is appropriate and make the desired adjustments without the intervention of third parties. The sense of autonomy and equality are completely liberating.

What have I learned in those three weeks?

MediaWiki’s documentation does not have a complete manual of style. This influences the quality of writing of technical documentation.
Documentation for translators and translation administrators is relatively extensive and, in some situations, difficult to read for beginners. This is because there’s no indication of who the target audience is, which makes the author make some assumptions. The most serious one is the level of familiarity of the reader with the software, the structure of the Wikimedia projects and their operation.
There are multiple resources for translators. However, when it comes to summarizing important information related to translations, the Meta-Wiki Meta: Babylon page is clearer, more succinct and easier to understand.
The process of reviewing translations, realistically, is a process with less priority. Therefore, providing good resources to translators is a more effective way to achieve the desired quality than recruiting people for that specific role.
Content for translation is marked manually. The process involves several strategies so that the translation is easily performed without causing fatigue, confusion or breakage of text.

The future

The phase of discussions and strategy building is approaching its end. In the coming weeks, I am expected to answer the following questions:

Is it possible to bring in new translators now? If so, how? If not, why?
What needs to be improved to welcome them better in the future?

I’ll write about that in the next post.

Understanding my role at Wikimedia

Mon, 27 Nov 2017 00:00:00 +0000

As I mentioned in my last post — My journey to Outreachy, or How I learned to stop worrying and start contributing —, I am one of the 42 people selected to work with FOSS projects as an Outreachy intern between December 2017 and March 2018. Since I already talked about my story and my application process, it’s time to write further about the foundation of my project (Translation outreach: User guides on MediaWiki.org).

According to the task T158296, translation of technical documentation is commonly neglected, leaving a lot of users without the option of reading it comfortably in their native language. Among the relevant tasks, it emphasizes the importance of finding places and communities where we can find potential volunteers, building strategies to recruit and test them, in addition to actions to ensure their permanence in the movement (and continuity of their work).

Investigating and understanding what motivates people to be volunteers on FOSS projects doesn’t only mean to check the available literature produced about the subject. Actually, this should be made with the objective of coming upon results that support your ideas and hypotheses. What is essential is the analysis of your own motivations — after all, you are part of this world as anyone else is. Ask yourself: what keeps you going?

My answers are the basis of my argumentation in my project proposal.

Common ground. FOSS projects frequently promote themselves as more ethical alternatives to proprietary solutions, besides values as open access, open knowledge, freedom and privacy. While we can find good contributors outside the user group, most of excellent contributions come from those who are already familiar with how the project works and believe in the project objectives, what leads us to the next motivator:
The urge to thank the welcoming community somehow, driven by a profound feeling of identification. In the article “Working for Free? Motivations for Participating in Open-Source Projects”, Alexander Hars and Shaosong Ou call this motivator community identification. The sensation of making part of something bigger encourage a “variant of altruism” which instigates those who contribute to execute positive tasks to the project (and its community) even if the outcome doesn’t benefit them directly. This encouragement, according to them, is equivalent to the need of to be loved and to belong described by Abraham Maslow. Stem from that, the objectives of those who contribute and their community become the same, nurturing the desire to see the project thrive.
Putting my abilities to proof and improving them, aside from the opportunity to learn new things. Oded Nov classifies this motivators under the categories Enhancement and Understanding in his article “What motivated wikipedians?”. FOSS projects are transparent about their operations and provide opportunities to learn and acquire countless abilities and forms of knowledge in a practical way (in contrast to classes at universities where there is a tendency to isolate learning to a single form of situation and expertise). It’s a multidisciplinary activity by nature, involving much more tasks than simply writing code and testing it such as project management, team work and documentation maintenance, steps as important as programming — or maybe even more fundamental, I’d dare to say. This systematic point of view promotes professional and personal flourishing, at the same time that allows a public promotion of your skills.

However, my work doesn’t involve just aspects related to volunteering — it’s a project targeting especially introductory, user documentation. Not only recruitment of new volunteers to make a localization effort is needed but also the analysis of the current state of documentation at Wikimedia, pointing strengths, weaknesses and devising plans to improve it. Tasks as unification of documentation are extremely relevant, especially because they affect the qualification of newcomers (hence the quality of contributions).

To observe the way other projects work, even if they are not similar to the ones Wikimedia Foundation promotes, it’s a great manner of evaluating Wikimedia and the FOSS scene as a whole. The retrieval of resembling initiatives through the history of the organization makes itself necessary, mainly to examine what are our limitations and what changed after all these years, making it possible or not to execute past ideas.

I am aware my internship has a short duration, making it difficult to make a deep impact on projects or change the prevalent culture on Wikimedia. Yet, I believe it’s achievable to make a wide study about multiple aspects involved by the scope of my project proposal and that my conclusions and reports can make a difference in long term, besides helping to come up with the solution to immediate problems.

My journey to Outreachy, or How I learned to stop worrying and start contributing

Mon, 13 Nov 2017 15:59:47 -0300

It was May of this year when, while I was reading some local news, I saw an announcement about the 5º Encontro Nacional de Mulheres na Tecnologia. The chance of meeting people with similar passions and experiences it’s always reassuring, so I immediately searched for more information. When I looked over its schedule, a Lighting Talk caught my attention: “Programa Outreachy: receba para estudar e trabalhar em projetos de software livre” (“Outreachy: get paid for studying and working on FOSS projects”) by Ana Rute Mendes, a former Outreachy intern at Mozilla. This unleashed a series of searches that led me to the conclusion it would be an amazing experience to me.

Even though I wanted to go to the meeting, I couldn’t — I was living a really turbulent moment in my life that required time and taking care of my mental health. However, I kept this information with great care after reading the list of proposed projects of the last round, assigning to the next months the beginning of my preparation for the application process.

Two months later, my immense dissatisfaction with Twitter made me exile from the platform. I went to Mastodon, where I got involved with its community, which since my first toot treated me really well and welcomed me with kindness. This ended up motivating me to communicate more in English — although I am a fluent speaker, I had little opportunities to use my second language.

After some time of use, feeling increasingly thrilled about the project and its userbase, I wished to thank them somehow. It didn’t take too long until I noticed the Brazilian Portuguese localization was quite similar to the European Portuguese one. After reading the translation guide and taking notes about the status of the corresponding files, I decided to start making small contributions.

According to my GitHub timeline, the first thing I made was to report an issue. I must confess I was really nervous before posting it — I still didn’t feel confident when expressing myself in English and I couldn’t shake off the feeling I was some kind of an impostor. I constantly asked myself if the things I was stating made sense or if I really should convey that information. Eight days later, with the help of Mastodon’s documentation, I learned to use git’s basic functionalities and submitted my first pull request. Looking back, I think I should have given more details about the changes I made and explained better my motivations, but that was a good start that encouraged me to produce the first full Brazilian Portuguese translation for Mastodon and keep maintaining it. I also provided the localization of the its landing page, joinmastodon.org, afterwards.

Although it surely sounds like a well planned path, it was a natural progression. I was always looking for the next thing to do for Mastodon, prompted by the urge of seeing new Brazilian users and the recognition of the importance of my work, and that led me to contributing to the localization of mobile apps like Tusky. These opportunities made me feel more and more passionate about this type of work, with which I’ve had only informal experiences: when enrolled to the Software Engineering for Avionics course at the Federal University of Goiás, I did a non-official translation of the Generic Avionics Software Specification report in a group assignment since I wanted to help team mates that had difficulties reading formal documents in English. From that education period comes my appreciation for the documentation process — something fundamental for critical systems —, some experiences with project management and software development, the adoption of the systematic perspective for problem-solving and a great technical background on aviation. This involvement surely shaped a lot of who I am professionally, enhancing my world perspectives and my abilities.

My contact with FOSS isn’t new as well, being a constant aspect of my life for almost seven years. From messing around with my first Android smartphone to today, I had experiences with SciLab; I went to events like Flisol (where I met my fiancé and a year later we did a talk together); I became an user of Linux distributions like Ubuntu, Elementary OS, Debian, Manjaro and the one I am currently using, Antergos; I learned how to use LaTeX, which completely revolutionized my academic life as a visually impaired undergraduate; I used NVDA when I had to deal with proprietary softwares without any accessibility options for low vision users on Windows… It was a matter of time until I finally would start to contribute.

In the first half of September, Outreachy began to announce which organizations would participate on the Round 15, and in September 11 I introduced myself to my possible mentors on Phabricator. When I read about the “Translation outreach” project, I was sure it was meant to be for me: it felt like the path I’ve taken until now prepared me to do it. This project was first announced on Round 14 and potential interns introduced themselves, but none of them actually applied. Keenly reading past discussions about it, I started to work on the microtask assigned as the required contribution, observe further debates with other applicants, make some questions and research further about related subjects. I also contacted the mentors privately to ask more personal questions about the required documents to prove enrollment in a university and expose some of my first ideas.

When I noticed I was about to finish the assigned microtask, I asked them what else could I do. Johan pointed out the Wikimedia Translators discussion list, to which I promptly subscribed. I also followed various Twitter profiles of Wikimedia’s projects and communities to understand more how they work. I would say this curious attitude was decisive to my application: through this course of action, I could comprehend better the communities’ culture when observing the way they communicate with the world and their peers and follow the latest technical changes on Wikimedia as I translated a new Tech News issue every week.

In addition to the form to be filled and submitted on Outreachy’s platform, Wikimedia requires applicants to publish a public project proposal on Phabricator. I published the first draft on October 9, two weeks before the deadline, and asked for feedback as I constantly worked on it to improve its contents. Antecedence and exclusive dedication to this task helped me craft a quality proposal, besides carefully listening to what my mentors had to say. You can read it here.

As the deadline passed, I kept making contributions, translating different parts of the documentation, dedicating Fridays to the Tech News and researches about the current state of Wikimedia. The only moment I decided to interrupt this workflow was three days before the results announcement: I recognized my efforts, noticed how anxious I was and gave myself some rest.

The application process was exhausting not for the amount of work, but for the emotional process. You are required to make long-term plans to present proposals, but at the same time this is emotionally stressful because you constantly carry within yourself the fear of creating too much expectations and ending up failing. You wish that days would come and go quickly and the results to get announced soon but simultaneously you don’t want it to happen too quickly since you are afraid of an outcome that won’t make you happy.

But sometimes, what seems impossible actually happens.

This is the first post of a series about my Outreachy internship at Wikimedia. Each one of them will be available in both Brazilian Portuguese and English, but feel free to translate them to any language of your choice as long as you respect the CC BY-SA 4.0 license. Thank you for reading and take care.

Anna writes

Thinking about FOSS, systemically

A macOS survival guide

Setting up your machine

Consequences of resetting your password

Shortcuts you should know

Clipboard management

Editing text files with nano

Window management

Window decorations

Deletion

Delete versus Forward Delete

If you need to use a macOS keyboard on Windows or vice-versa

Installing applications

System operations

Using an iPad with a Mac

Favorite applications

Daily planning and stand-ups

How we communicate

Our emoji key

My tools

My system

How to make Linux properly dectect your ZSA keyboard

TL;DR

Installing Wally’s dependencies on Linux

Creating a udev rule for Wally and Oryx

References

Footnotes

How did Open Collective's docs change in three months?

What’s new?

Our project in numbers

What’s left to do?

Is GitBook the right tool for your organization?

What does it do well?

Uncomplicated set up

Draft system

Shortcodes

What could be better?

GitHub integration

Releases

What isn’t good about it?

Vague and/or incomplete documentation

Lack of functionalities (that the old version used to have)

Accessibility

Well, should Open Collective adopt a new platform or software to manage their documentation?

My first impressions of GitBook

Documentation platforms & tools I’m familiar with

MediaWiki

Pros

Cons

Resources

Git (or any other version control system) related

Pros

Cons

Pros

Cons

Pros

Cons

In between

GitBook

Open Collective’s contribution guide

Welcome page

Summing up

Understanding Open Collective's documentation

Historical review

Mapping

Initial analysis

Methodological Roadmap

MozFest is a reminder that the world can be a great place

My MozFest experience

October 27

Is the Netflix of podcasts inevitable? (Decentralisation)

Sociocracy: a practical introduction to consent-based decision making (Decentralisation)

Defying our senses to promote diversity and inclusion in science communication with IGNITE (Decentralisation)

Design for Renaming (Privacy and Security)

October 28

The Hidden Fragility of the Internet (Web Literacy)

Decentralized Web Standards: From ActivityPub to Webmention (Decentralisation)

Ephemeral, lost, forgotten: how to help to preserve human history in an ever-changing world (Decentralisation)

Highlight: the Decentralisation space

`Delete` versus `Forward Delete`

Creating a `udev` rule for Wally and Oryx