[Season of Docs] · 19 de agosto de 2019 · 6 min de leitura

Entendendo a documentação do Open Collective

Como documentarista, o meu trabalho vai além da escrita técnica: ele envolve uma análise sistêmica (não confundir com sistemática) da documentação em relação ao projeto. Por isso, sempre que começo a trabalhar com um projeto aberto, eu me faço as seguintes perguntas:

1. Qual é a história da documentação do projeto com o qual estou trabalhando? Em que plataformas ela já esteve disponível?
2. Qual é o tamanho da documentação? Quantas páginas são relevantes para o trabalho que farei?
3. Qual é o método de categorização usado atualmente? Quais são as personas (perfis de leitores) que a documentação procura informar?
4. Qual é o estilo de escrita da documentação? Ele é consistente? Há um guia de estilo que orienta a escrita da documentação?

Neste texto, entenderemos um pouco mais sobre a documentação atual do Open Collective, a organização que me acolheu nesta rodada do Google Season of Docs.

Open Collective é uma plataforma de financiamento online para comunidades abertas. Ela fornece ferramentas para levantar e administrar recursos financeiros ao mesmo tempo que facilita o compartilhamento de suas finanças com os seus financiadores com bastante transparência.

Trabalhar abertamente é um dos valores nos quais mais acredito e um dos pontos em que mais me frustro com algumas comunidades de software livre — o que me levou a escrever o texto Código aberto != trabalhar abertamente. Por isso, quando vi o Open Collective na lista de organizações participantes do Google Season of Docs, tive a sensação de que estávamos destinados a trabalhar juntos.

A maioria das referências a páginas externas neste texto te levarão diretamente às versões arquivadas no Internet Archive para preservar o contexto histórico deste relatório.

Histórico

Antes de estar disponível sob domínio próprio no GitBook ^[arquivado] , a documentação do Open Collective era disponibilizada e editada na wiki do projeto no GitHub ^[arquivado] sem muitas opções de personalização e nenhuma categorização de páginas. Novas seções eram (e continuam sendo) criadas de acordo com a demanda recebida por canais de comunicação como e-mail, Slack e o sistema de tickets no Zendesk.

Ter acesso à documentação obsoleta quando ela já foi atualizada ou movida é raro, mas quando possível, é uma fonte e tanto de aprendizado. Por exemplo, quase não há uso de mídia como imagens, GIFs ou vídeos na wiki (e quando há, elas estão quebradas por causa do processo de migração pelo qual passou). Há também muitas páginas cujo conteúdo gira principalmente em torno de referências a páginas externas (como esta seção que fala sobre widgets). Isso torna bastante perceptível que, junto com a mudança de plataforma, houve uma mudança positiva de estilo e cultura.

Mapeamento

Da wiki do GitHub ao GitBook, a documentação ganhou um pouco mais de 60 páginas adicionais e hoje é estruturada da seguinte forma:

Análise

Todas as seções estão dentro do escopo do meu projeto (“Improve general help documentation”) de uma forma ou de outra: seções focadas em cultura como The Open Collective Way e seções centradas em personas como Collectives, Backers & Sponsors e Fiscal Hosts têm um objetivo claro de ajudar usuários e merecem atenção redobrada. Já as seções Developers, Internal e Design, apesar de não serem exatamente o foco do projeto, abrigam páginas relevantes e precisam sofrer algumas modificações em sua estrutura.

Perceba que a categorização das seções e páginas derivadas, assim como o padrão de nomes, não é consistente — um indício de que elas foram criadas seguindo diferentes demandas sem um projeto de organização único em mente. Há também um número razoável de páginas duplicadas (como Translators e Community Guidelines) e páginas que podem ser unidas em uma seção única da documentação sem prejuízos (páginas sob Developers, Design e About relacionadas a contribuições no Open Collective; páginas sob About e Product).

A página inicial também não auxilia o leitor a se relacionar como uma das personas atendidas pela documentação. Quem são (ou podem ser) core contributors, collectives, backers, sponsors, fiscal hosts? Na configuração atual, você precisa visitar cada seção para entender o papel de cada um — e algumas dessas páginas estão escondidas sob seções com nomes que não sinalizam o seu tema com sucesso. Você seria capaz de adivinhar que a documentação referente a core contributors está sob The Open Collective Way quando outras personas têm seções especialmente dedicadas a elas?

O estilo de escrita é principalmente conversacional. A documentação se dirige ao leitor diretamente várias vezes (como na resposta "You've come to the right place!") e simula possíveis questionamentos (como na pergunta "Can I get a receipt for my donations?"). Em alguns momentos, a documentação também adota uma linguagem instrucional (como na página Edit Collectives). No entanto, não existe um guia de estilo para a documentação do Open Collective.

Com tudo isso em mente, como devemos proceder?

Roteiro metodológico

Adotarei o seguinte roteiro nos dias restantes do período de Community bonding:

Adicionalmente, compartilharei ideias e descobertas no canal #documentation do Slack do Open Collective. Se você tem interesse em acompanhar essa discussão, sinta-se à vontade para se juntar a nós!