/ Localizando-me / blog

Entendendo a documentação do Open Collective

August 19, 2019 · 6 min read · PT-BR > reports > open collective > documentation

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.

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:

  • 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 Tranfers
    • 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

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:

  • Análise detalhada de todas as páginas
    • Qual é o assunto principal desta página?
    • A quem ela se dirige?
    • Seu tom é conversacional ou instrucional?
    • Há algum tipo de mídia nessas páginas?
      • Se sim, elas precisam ser atualizadas?
      • Se não, devemos acrescentar algum tipo de mídia?
  • Identificação dos temas em comum entre grupos de páginas
  • Proposta de uma nova estrutura
  • Submissão para comentários e sugestões
  • Apresentação do plano final de reestruturação

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!


⌨️ About the author

Anna e só is a documentarian who loves working with open projects and takes pride in offering them a unique point of view. They are currently working with Open Collective as a Google Season of Docs technical writer. They are also an Outreachy helper and a technical consultant in the project Free Software Ecosystems from LAPPIS/UnB. In their spare time, they are usually breaking and rebuilding things such as this blog theme.

👋 Related posts in the Jornada pelo Google Season of Docs series...