Um README para dados de pesquisa é a porta de entrada do conjunto. Ele explica o que foi coletado, quem produziu os arquivos, como a coleta ocorreu, quais transformações foram aplicadas, como as pastas se relacionam e sob quais condições o material pode ser acessado ou reutilizado. Seu objetivo não é repetir cada coluna do dicionário de dados, mas oferecer contexto suficiente para que uma pessoa externa reconheça o conteúdo e saiba onde procurar detalhes.
Escreva o README antes do depósito final e mantenha-o durante o projeto. Começar cedo revela lacunas de nomenclatura, versões e proveniência quando ainda há tempo de corrigi-las. Use formato aberto e legível, como texto simples ou Markdown, nome estável e linguagem direta. Evite depender de links temporários, conhecimento oral da equipe ou caminhos existentes apenas no computador de quem fez a análise.
Identifique o conjunto e sua responsabilidade
Abra com título, resumo e responsáveis. Informe autores ou equipe, instituição, contato persistente quando apropriado, projeto relacionado e período coberto. Se o conjunto possui DOI, versão ou data de publicação, registre esses elementos. Diferencie quem criou os dados, quem os organizou e quem pode responder sobre acesso; esses papéis nem sempre coincidem.
Descreva a finalidade original e a unidade de observação. Dizer “dados de entrevistas” é insuficiente: indique população ou contexto, recorte temporal, modalidade de coleta e natureza dos arquivos, sem expor participantes. Para experimento, identifique condições e repetições. Para dados secundários, cite a fonte original, condições de uso e transformações realizadas.
O resumo deve permitir que alguém decida se o conjunto é pertinente antes de baixar tudo. Inclua também uma citação sugerida quando já houver registro persistente e relacione publicações derivadas. Se a publicação ainda está sob avaliação, não invente referência; indique o estado real e atualize depois.
Apresente a estrutura de pastas e arquivos
Liste os diretórios e arquivos distribuídos, com função, formato e relação entre eles. Explique qual arquivo é bruto, limpo, derivado ou de saída; informe se uma pasta será criada por script e se algum material não acompanha o depósito. Nomes como dados_finais.xlsx não revelam proveniência. Prefira convenções estáveis e descreva-as.
Uma árvore curta pode ser útil, desde que corresponda exatamente ao pacote. Depois dela, explique a ordem de uso: qual arquivo entra primeiro, que script produz a base analítica e onde aparecem tabelas e figuras. Se a estrutura muda entre versões, atualize o README na mesma mudança, não meses depois.
A Cornell Data Services recomenda documentar dados com informações sobre título, autores, metodologia, compartilhamento, arquivos e detalhes necessários à reutilização. Adapte os campos ao seu domínio e às exigências do repositório, sem transformar o modelo em formulário preenchido mecanicamente.
Registre coleta, processamento e controle de qualidade
Explique quando, onde e como os dados foram obtidos, os instrumentos usados, critérios de inclusão e exclusão, amostragem, calibração e unidades de medida. Cite protocolos ou publicações que detalham o método, mas não terceirize toda a compreensão para um link. O README deve preservar o contexto essencial mesmo se uma página externa mudar.
Descreva cada transformação que afeta interpretação: anonimização, remoção de duplicatas, recodificação, imputação, agregação, arredondamento, filtragem e correção manual. Relacione o dado bruto ao derivado e identifique scripts, versões de software ou parâmetros quando necessários. Se uma etapa não pode ser reproduzida por restrição, explique a limitação.
Inclua verificações realizadas e problemas conhecidos. Informe valores ausentes, cobertura desigual, erros de instrumento, mudanças de definição e observações excluídas. Uma limitação clara aumenta a utilidade do conjunto porque evita conclusões incompatíveis com o que foi medido. Não apresente dado limpo como se nunca tivesse exigido decisões.
Separe README, dicionário de dados e documentação do método
O README orienta o conjunto; o dicionário descreve campos e códigos. Para cada variável, o dicionário deve registrar nome, definição, tipo, unidade, valores permitidos, códigos de ausência e, quando pertinente, origem e transformação. Em bases relacionais, documente chaves, cardinalidade e regras de junção.
Protocolos extensos, cadernos de código, formulários e manuais podem ficar em arquivos próprios. O README os indexa e explica por que importam. Essa divisão evita um documento impossível de navegar e, ao mesmo tempo, impede que anexos soltos percam conexão com a base.
Padronize termos entre arquivos. Se o README chama uma tabela de “participantes”, o dicionário não deve usar “respondentes” sem explicar equivalência. Datas, unidades e códigos de ausência precisam coincidir com o conteúdo real. Faça validações automáticas quando possível e uma leitura manual centrada no significado.
Explique acesso, ética, licença e reutilização
Declare se os dados são abertos, restritos, sob embargo ou indisponíveis. Quando houver restrição, informe motivo, autoridade responsável, critérios e procedimento de solicitação, sem prometer acesso automático. Uma declaração de disponibilidade de dados no artigo deve apontar para a mesma realidade descrita no pacote.
Não trate anonimização como garantia absoluta. Indique medidas aplicadas, risco residual relevante e condições aprovadas pelo comitê de ética ou pela instituição. Remova dados pessoais do próprio README. Para materiais de terceiros, diferencie o que a equipe pode documentar do que pode redistribuir.
Informe licença apenas quando os titulares podem concedê-la. Especifique versão e endereço persistente dos termos. Se partes do conjunto possuem condições diferentes, identifique cada escopo. Também registre a forma de citação e eventual obrigação de reconhecer a fonte original, sem criar exigências incompatíveis com a licença adotada.
Ao escolher um repositório para dados de pesquisa, confira metadados exigidos, formatos aceitos, preservação, versionamento e controles de acesso. O README complementa o registro do repositório; não substitui campos estruturados nem termos da plataforma.
Use uma sequência mínima de revisão
Antes do depósito, faça uma leitura como se não conhecesse o projeto:
- confirme título, autoria, versão, DOI, contato e escopo do conjunto;
- compare a lista de arquivos com o pacote efetivamente enviado;
- teste a ordem de processamento em uma pasta limpa e registre dependências;
- confronte variáveis, unidades e códigos com o dicionário e os dados;
- revise restrições, licença, citação, limitações e links persistentes;
- peça a uma pessoa externa à preparação para localizar e interpretar uma observação.
O teste externo é decisivo. Peça que a pessoa encontre a base analítica, explique uma variável, reconheça um valor ausente, identifique a origem de um resultado e diga o que pode reutilizar. Anote onde ela precisou perguntar. Cada dúvida recorrente indica documentação ausente ou ambígua.
Atualize a documentação com cada versão
Dados publicados podem receber correções, novos arquivos ou documentação melhor. Registre número da versão, data, natureza da mudança e impacto sobre resultados. Não substitua silenciosamente um conjunto que já foi citado. Preserve versões anteriores quando o repositório permitir e indique qual deve ser usada.
Adote uma regra simples: nenhuma alteração de arquivo distribuído entra sem avaliação do README e do dicionário. Em projetos versionados com Git, a documentação pode acompanhar scripts e arquivos textuais; bases grandes permanecem no armazenamento adequado, vinculadas por identificadores e registros de versão.
As boas práticas de documentação da Dryad reforçam que arquivos devem ser compreensíveis, usar formatos adequados e incluir informação suficiente para reutilização. Requisitos variam por disciplina, repositório e natureza dos dados, por isso modelos genéricos precisam ser ajustados ao caso concreto.
Um README eficaz reduz a distância entre “ter acesso aos arquivos” e “entender o conjunto”. Ele identifica o objeto, mostra sua estrutura, registra proveniência, explica limites e orienta uso responsável. Quando outra pessoa consegue interpretar os dados sem depender da memória da equipe, a documentação passou a integrar de fato a qualidade da pesquisa.
