Como construir Comunidades Open Source com Documentação de Software: exemplo NumPy

As Comunidades Open Source são um espaço excelente para experimentar, adquirir experiência técnica, e construir relacionamentos profissionais. Ao longo deste conteúdo você aprende um pouco mais sobre quais são, como funcionam, e como a documentação de software as fortalece.

Para começar, você deve saber que esse conteúdo foi elaborado com base na conversa com a matemática Melissa Weber Mendonça, Engenheira de Software da Quansight. Ela traz consigo uma história bonita (e de muita garra!) sobre como conseguiu transicionar de carreira em 2020, em plena pandemia. Descobriu paixões até então desconhecidas: a documentação de processos de desenvolvimento de software, e as comunidades Open Source. Descubra como funcionam e como você pode fazer parte.

Quer acompanhar a conversa inédita e sem cortes? Assista à Ubitalk aqui:

Quer aprender mas falta tempo? Leia o resumo adaptado.

Antes de mais nada: Como funcionam as comunidades Open Source? 

Antes de ir a fundo, é importante que você esteja a par dos conceitos básicos. Vamos a eles.

O que é Open Source?

Open Source (Código-fonte aberto) é o termo usado para definir os programas de computador, mobile e web, cujo código de programação em si é público. Em outras palavras, qualquer pessoa pode acessá-lo, modificá-lo e distribuí-lo livremente, num grande esforço colaborativo.

• Para os desenvolvedores de software, isso significa que é possível aprender com milhares de outros colegas que contribuíram com a construção. Focam apenas em melhorar algo já existente, ao invés de começar um novo programa (concorrente) do zero.
• Para os usuários de softwares de código aberto (não confundir com software livre!), o ganho está na possibilidade de testar gratuitamente o produto final; o que não impacta, obrigatoriamente, o custo de compra deste software. 

A principal diferença entre código aberto (open source) e código fechado (proprietary software) é, portanto, que qualquer especialista pode acessar e avaliar estes programas. A Optimus Information lançou um whitepaper esclarecedor, em inglês. Confira: Open Source vs. Proprietary Software Pros and Cons.

Existem centenas de Open Source Software (OSS) disponíveis. Exemplos mais conhecidos incluem o navegador Mozilla FireFox, o Chromium da Google, e a suite do LibreOffice.

Quais as principais características dos OSS?

Para ser considerado código open source, o software deve seguir as definições estabelecidas pela Open Source Initiative. Resumidamente, são dez diretrizes:

1. Redistribuição gratuita
2. Distribuição em código-fonte e em forma compilada
3. Permissão para Obras Derivadas e modificações
4. Preservação da Integridade do Código-Fonte do Autor
5. Sem discriminação contra pessoas ou grupos
6. Sem discriminação contra campos de atuação
7. Sem necessidade de Distribuição de Novas Licenças
8. As licenças não devem restringir outro software
9. As licenças devem ser neutras em termos de tecnologia

Jono Bacon é uma das principais autoridades na área. Fica a dica de leitura: People Powered – How Communities Can Supercharge Your Business, Brand and Teams. 

Quais as principais Comunidades Open Source?

Em suma, as comunidades Open Source são grupos semi-organizados de indivíduos que contribuem ativamente para construir software juntos. São pessoas que doam o seu tempo e conhecimento para trazer melhores resultados para os usuários dos programas que consideram necessários para a transformação digital.

Sobram comunidades Open Source, gerando aplicativos para os mais variados fins. Além dos nomes que já citamos, alguns exemplos incluem Linux, Apache, WordPress, e Facebook (React Native). 

Voltando à Ubitalk da Melissa, temos o exemplo da NumPy, uma biblioteca para computação científica no Python. Daqui para a frente, entramos em mais aprofundamento técnico. Prepare-se!

O que é a biblioteca NumPy?

Dentro da linguagem de programação Python, programadores utilizam vários pacotes do Python para fazer aplicações científicas. A NumPy é a biblioteca que fornece a estrutura de dados básica para se fazer processamento numérico. Contudo, grande parte das partes mais fundamentais dela são escritas em C.

É isso que faz ela ser rápida e ter um desempenho satisfatório para quem quer fazer computação científica, que é um campo um pouco diferente da programação habitual:

• Em outras áreas da programação, o foco está na legibilidade.
• Na computação científica, a prioridade está na velocidade de processamento.

Isso porque na computação científica os problemas são gigantes. É preciso que a resolução deles tenha bom desempenho. Hoje, a NumPy permite a criação de aplicações de ciência de dados para processamento de imagem, sequenciamento genético, pesquisas na área da saúde, telecomunicações, e muitas outras. 

Para se ter uma ideia do impacto, a biblioteca NumPy teve 42 milhões de downloads apenas em novembro de 2020. Não por acaso, o projeto de manutenção dela já recebeu 1,5 milhões de dólares (a comunidade possui cerca de dez mantenedores ativos). Importantíssimo, considerando que o trabalho da comunidade é majoritariamente voluntário.

Nos anos 1990, duas bibliotecas concorrentes eram usadas para a computação científica em Python. Em 2006, elas fundiram-se para fundar a NumPy. Dali para a frente, vários pacotes para processamentos de arrays (vetores) – em outras palavras, álgebra linear. Foram criadas em cima dela, ou a replicam na compilação, para computação paralelas, etc. 

O que é Documentação de Software e porque ela é crucial para as Comunidades Open Source?

Em linhas gerais, a documentação de software é o registro de como o programa é desenvolvido e utilizado. O principal objetivo é que ela sirva para alinhar que tanto os desenvolvedores quanto os demais stakeholders caminhem juntos. 

Software Documentation involves both product and process documentation

É comum se falar em documentação de API, ou especificação de API. Mas há muito mais por desvendar! Melissa usa o Python como exemplo:

• Docstrings: é a documentação colocada no topo de cada função, explicando o que ela faz. Pode ser extraída de maneira automática posteriormente para gerar uma especificação de API.
• Documentação narrativa: normalmente chamada de tutorial ou how-to.
• Conteúdo educacional: independente de mídia e formato (vídeo, podcast, live stream).

Tudo que é registrado e consumido, inclusive o streaming de código, conta como documentação. O importante é que sirva de apoio para quem precise consultar determinado termo ou precise lidar com diferentes componentes da biblioteca. Respostas no Stackoverflow e comentários do GitHub também valem.

Quer saber como funciona um sistema de documentação? Confira esse vídeo de uma palestra do Daniele Procida:

Esse exemplo do Divio também é uma excelente referência, explicando inclusive os tipos de documentação. 

Ferramentas usadas na documentação de software

Existem muitos recursos úteis, mas Melissa destaca alguns específicos. Primeiro, a Sphynx, ferramenta utilizada para a coleta e análise de dados, usada para identificar codestrings. Segundo, a complementaridade da MyST, uma nova sintaxe aplicada à Sphynx, porém em linguagem markdown. 

Por último, fica a dica de uso do Jupyter Notebooks. A plataforma serve para criar e compartilhar documentos que contenham código ativo, equações, visualizações e texto narrativo. Tudo open source.

As comunidades Open Source são dinâmicas e sofrem com a rotatividade dos seus contribuidores.

Por isso, é fundamental registrar e potencializar o conhecimento gerado pelas comunidades. No caso da NumPy, há um time de documentação. Você pode se inspirar na maneira em que ele está estruturado, olhando aqui.

Expandir o código de uma maneira acessível e inteligente passa, invariavelmente, por facilitar a sua compreensão e aplicação. Projetos importantes precisam deste nível de organização.

Como exemplo, Melissa cita a fundação Chan Zuckerberg Initiative, a qual se dedica a encontrar financiamento para projetos open source trabalhando na esfera científica em qualquer linguagem de programação. O requisito é que sejam voltadas para aplicações biomédicas.

A Fundação tem como missão encontrar uma cura para todas as doenças conhecidas até o final da década de 2030. Para tanto, lançou programa para financiar softwares open source tidos como essenciais para a ciência. 

Porém, ao contrário de modelos tradicionais, exige explicitamente dos projetos open-source que parte do financiamento seja utilizado na manutenção e na documentação, por exemplo. O que é inovador – normalmente, o repasse de verbas se destina apenas à construção de novas features.

A importância da documentação para a saúde de projetos de software

Assim como outros aspectos estruturais, a documentação apoia a construção e o fortalecimento da comunidade open source por:

• Prepara diferentes pessoas para atuar no projeto
• Facilita que os membros da comunidade possam alternar em posições de poder
• Organiza as definições estruturais 

Como, então, as comunidades Open Source podem se organizar? No caso da NumPy, foi estabelecida até mesmo uma metodologia de atualização da documentação. O passo-a-passo é mais ou menos assim:

1. Há um local centralizado, o PP – Python Proposal – para as decisões da comunidade;
2. Quando há uma proposta de melhoria para a linguagem, cabe à pessoa submeter uma proposta por escrito;
3. A sugestão é então debatida pela comunidade online, em um processo construtivo de ampliação e melhoria;
4. Se e quando a proposta é aceita, ela passa a ser implementada.

Quer continuar aprendendo? 

Fica novamente o convite para assistir a Ubitalk com a Melissa, mas também vale a pena você acompanhar a playlist das Ubitalks no nosso YouTube. Lá você encontra conteúdos técnicos em primeira mão, além de dicas de carreira. Tem muitas coisas boas esperando por você, em português e inglês! Tem uma, aliás, que super recomendamos. Clique no link e se inscreva!

Quer trabalhar remoto com TI para os EUA e Canadá?

Se você tem vontade de dar o pontapé e desenvolver sua carreira internacional, preencha o form abaixo para fazer parte da Talent Pool da Ubiminds. Deixa que a gente cuida do resto! 😉

Mariana Alves

Mariana Alves é uma entusiasta de tecnologia e jogos, além de ser uma profissional de marketing orientada por dados. Mari promoveu SaaS, Games e Apps em mercados globais (EMEA, Reino Unido, EUA, Brasil), acumulando mais de 5 anos de experiência em trabalho remoto.