Brasil Participativo: Outubro de 2025
Quando pensamos em modelos de documentação para projetos abertos, precisamos considerar aspectos relacionados ao propósito, distribuição e disponibilidade da informação. Para informar aspectos sobre propósito, gosto da abordagem de Diátaxis com quatro formas de documentação: tutoriais (i.e. lições que transmitem conhecimento através da ação — uma forma de realizar um estudo), guias (i.e. instruções para pessoas com mais conhecimento — uma forma de realizar um trabalho), referências (i.e. referências técnicas, conhecimento teórico, mas com a aplicação de uma habilidade) e explicações (informações contextuais, enriquecimento do estudo de um usuário). Esta tabela adaptada nos traz um excelente resumo das diferenças entre os quatro tipos de conteúdo:
| Tutoriais | Guias | Referências | Explicações | |
|---|---|---|---|---|
| função | introduzir, educar, liderar | guiar | afirmar, descrever, informar | explicar, esclarecer, discutir |
| pergunta central | “você pode me ensinar a fazer X?” | “como eu faço X?” | “o que é X?” | “por que X?” |
| orientado a | aprendizado | objetivo | informação | entendimento |
| propósito | prover uma experiência de aprendizado | alcançar um objetivo específico | descrever o mecanismo | esclarecer um tópico |
| forma | lição | uma série de passos | descrição “seca” | explicação discursiva |
| analogia | ensinar uma criança a cozinhar | uma receita em um livro de receitas | informação na embalagem de um alimento | um artigo sobre a história da culinária social |
O propósito também está interligado a personas de leitores que esperamos que leiam o que escrevemos—isto é, o perfil de leitor. Pedaços significativos da documentação podem ajudar múltiplas personas, mas é esperado que seções específicas sejam destinadas proeminentemente a personas específicas. Cada persona acessa a documentação em busca de uma informação específica adequada ao seu nível de acesso e entendimento do sistema.
Já quanto aos aspectos de distribuição e disponibilidade em documentação, os dois são profundamente inter-relacionados. Poderia ainda acrescentar um sub-aspecto, destinação. Quando participei das minhas primeira reuniões sobre o Brasil Participativo, fui informada que o projeto começou como um fork profundo do Decidim—muitas modificações o distanciaram do upstream. Em situações como essa, o apropriado é também criar um fork da documentação técnica do projeto de origem e manter uma perspectiva clara das características que os diferenciam. O escopo desse tipo de documentação é monumental.
No entanto, ao se tornar mais maduro, o projeto começou então um movimento de modularização do núcleo específico do Brasil Participativo. Em outras palavras, o Brasil Participativo se torna agora um componente do ecossistema original do Decidim. Nesse caso, a documentação produzida pela equipe do Brasil Participativo deve ser referente apenas à integração dos módulos ao Decidim. Quaisquer assuntos de competência do núcleo do Decidim deve ser empacotada como contribuição ao upstream ou direcionada à documentação original. O escopo da documentação de módulos é significativamente menor em relação à alternativa anterior, mas engloba tanto informações relevantes aos usuários do sistema quanto informações para os mantenedores do sistema em uma configuração própria.
Há, ainda, o projeto complementar de oferecer o Brasil Participativo como SaaS (software as a service) em território nacional. A documentação apropriada para essa iniciativa está contida nos esforços correspondentes ao escopo descrito no parágrafo anterior. Mas ainda há alguns aspectos interessantes a serem discutidos sobre a sua disponibilidade e distribuição:
- Devemos ter uma única documentação centralizada ou um espelho da documentação em cada instalação (sob uma URL personalizada)?
- Como sincronizar a documentação com as atualizações do software? Sob a competência de que pessoas ou equipes devem ficar essas atualizações?
- Como conciliar contribuições externas, isto é, de pessoas que não compõem as equipes de desenvolvimento do Brasil Participativo?
Observando as interações com busca de informações nos canais do Telegram do Brasil Participativo—onde também há um controle de bugs e captura de relatos de usuários—, acredito que a filosofia de estruturação e publicação de documentação mais apropriada para o Brasil Participativo é a docs-as-code (exemplos notórios não faltam neste link). A integração de controle de versões via Git ou outro sistema similar permite mais flexibilidade às respostas das perguntas acima. Há, no entanto, uma necessidade da integração de escritores com as equipes de desenvolvimento. É exatamente esse o meu próximo principal desafio: entender a cultura, os ritos e o ritmo de desenvolvimento do Brasil Participativo.
Levantamentos-alvo dos próximos 30 dias:
- Definição mais clara de personas
- Mapeamento de documentação pública
- Mapeamento de documentação privada
- Mapeamento do pipeline documental usual