Versionamento, documentação e princípios FAIR

IM-1256 - Introdução à História Digital

Eric Brasil

2024-11-19

Planejamento da pesquisa

• Documentação
• Organização
• Preservação
• Licenciamento

Plano de gerenciamento de dados

• Plano de Gerenciamento de Dados (Data Management Plan - DMP)
• Documento vivo atualizado durante a pesquisa.
• Exemplos e diretrizes disponíveis no OSF.
• The Digital Documentation Process

é importante definirmos, mesmo que de forma geral e preliminar, o planejamento específico voltado para documentação, organização, preservação e licenciamento da pesquisa.

Ou seja, é fundamental a elaboração de um plano de gerenciamento dos dados (DMP, do inglês Data Management Plan), que deve ser elaborado nessa primeira fase e atualizado ao longo do seu desenvolvimento.

O Open Science Framework (OSF) possui um conjunto de documentações de suporte específicas sobre o tema, e podem ser acessadas aqui.

Além do OSF, indicamos a leitura e avaliação do The Digital Documentation Process, que apresenta valiosas reflexões e diretrizes para catalogar e preservar objetos digitais.

Estratégias de Documentação

• Finalidade: Capturar o processo de criação de dados e alterações.
• Capacidade de preservar, recuperar, compartilhar e reutilizar os dados de uma pesquisa passa sobremaneira pela a forma como esses dados são documentados.

Estratégias de Documentação

James Baker, Preservar os seus dados de investigação.

1. escrever explicitamente os critérios e os padrões adotados.
2. utilizar formatos de texto simples e multiplataforma, como txt, md e csv;
3. incluir README.md ou README.txt em cada diretório explicitando seu conteúdo;
4. padronizar nomeação de diretórios e ficheiros;

Estratégias de Documentação

James Baker, Preservar os seus dados de investigação.

5. pensar em formatos, padrões e convenções que sejam multiplataforma;
6. registar suas decisões;
7. produzir a documentação de forma continuada, durante todo o processo de pesquisa.

O que é o README?

Sobre arquivos README, veja a documentação do GitHub. Aqui um exemplo de README explicando o conteúdo de um diretório: README.md.

Estratégias de Organização

1. Pensar estrutura de diretórios padronizada;
2. Nomear ficheiros de forma padronizada;
3. Criar padrão de realização de backups;
4. Explicitar o uso de serviços de nuvem e sincronização de dados.
5. Avaliar ferramentas de organização de dados e referências bibliográficas.
6. Incluir decisões de organização na documentação.

Estrutura de diretórios

Exemplo simples de estrutura de ficheiros e diretórios.

Estrutura de diretórios

HEMDIG(pt): Métodos, ferramentas e hemerotecas digitais em português:

Estrutura de diretórios e ficheiros do repositório do HEMDIG(pt)

Princípios FAIR

• Guia para organização e documentação de dados:
  1. Findable (Encontrável)
  2. Accessible (Acessível)
  3. Interoperable (Interoperável)
  4. Reusable (Reutilizável)
• Detalhes em: FAIR Principles

Uma outra filosofia que pode nos ajudar a pensar a organização dos dados é o FAIR. Do inglês Findability, Accessibility, Interoperability, and Reuse de dados digitais, o FAIR nos indica princípios que devem guiar a nossa elaboração de estratégias de organização e documentação de dados.

1. Encontrável (Findable)

• F1. Os (meta)dados recebem um identificador global único e persistente.
• F2. Os dados são descritos com metadados ricos (definidos em R1 abaixo).
• F3. Os metadados incluem clara e explicitamente o identificador dos dados que descrevem.
• F4. Os (meta)dados são registrados ou indexados em um recurso pesquisável.

2. Acessível (Accessible)

• A1. Os (meta)dados são recuperáveis pelo seu identificador, utilizando um protocolo de comunicação padronizado.
  • A1.1 O protocolo é aberto, gratuito e universalmente implementável.
  • A1.2 O protocolo permite um procedimento de autenticação e autorização, quando necessário.
• A2. Os metadados são acessíveis, mesmo quando os dados não estão mais disponíveis.

3. Interoperável (Interoperable)

• I1. Os (meta)dados utilizam uma linguagem formal, acessível, compartilhada e amplamente aplicável para representação do conhecimento.
• I2. Os (meta)dados utilizam vocabulários que seguem os princípios FAIR.
• I3. Os (meta)dados incluem referências qualificadas a outros (meta)dados.

4. Reutilizável (Reusable)

• R1. Os (meta)dados são descritos com uma pluralidade de atributos precisos e relevantes.
  • R1.1. Os (meta)dados são disponibilizados com uma licença de uso clara e acessível.
  • R1.2. Os (meta)dados são associados a uma proveniência detalhada.
  • R1.3. Os (meta)dados atendem aos padrões comunitários relevantes para o domínio.

Licenciamento de Dados

• Escolher licenças que incentivem:
  • Acesso
  • Reutilização
  • Transparência
• Sugestões:
  • Creative Commons
  • Choose a License

Uma prática importante, mas ainda pouco usual no campo das Humanidades é a definição de uma licença de uso para os dados gerados durante a pesquisa.

Como parte significativa de nossas pesquisas utiliza dados públicos e é financiada também por recursos públicos, é importante escolhermos licenças que permitam o acesso, mas também a reutilização dos dados por outros pesquisadores.

Obviamente precisamos levar me conta questões éticas e legais para a definição da licença, mas é importante que a escolha seja feita de forma consciente e documentada.

Para dados e materiais que não sejam programas de computador, é recomendado a utilização de licenças Creative Commons, que permitem a reutilização dos dados, desde que citada a fonte e a licença original.

No site Choose a License é possível encontrar uma lista e indicações de quais licenças mais apropriadas para cada tipo de material e pesquisa.

Sistema de controle de versões

Eric Brasil, “Git como ferramenta metodológica em projetos de História (parte 1)”, Programming Historian em português 3 (2023), https://doi.org/10.46430/phpt0045.

• O que é um SCV (Sistema de Controle de Versões)?
  • Registra mudanças de arquivos ao longo do tempo.
  • Exemplo: Git

Uma das estratégias mais robustas de documentação e organização da pesquisa é a utilização de um sistema de controle de versões, como o Git. Apesar de possuírem uma curva de aprendizado mais acentuada, os SCVs são ferramentas poderosas para o controle das alterações e o registro das decisões e escolhas ao longo do processo de pesquisa.

Em artigo recente publicado no Programming Historian, intitulado Git como ferramenta metodológica em projetos de História (parte 1), explico o que é um SCV:

Um SCV consiste em um sistema que registra as mudanças de um ficheiro ou conjunto de ficheiros ao longo do tempo, cada uma dessas mudanças é acompanhada de um conjunto de metadados (ou seja, informações sobre os dados), e te permite recuperar tanto esses dados quanto o estado em que se encontrava o seu projeto há época.

É como se você possuísse uma máquina do tempo capaz de te levar de volta a qualquer ponto da história de mudanças da sua pesquisa.

Sistema de controle de versões

• Benefícios:
  • Rastreabilidade de mudanças.
  • Reprodutibilidade de projetos.
  • Segurança e integridade dos dados.
  • Colaboração e compartilhamento de dados.

Git

Vamos fazer a lição do Programming Historian juntos?

O Git é um SCVs de arquitetura distribuída. Foi criado em 2005 por Linus Torvalds1 e atualmente é o mais popular do mundo (em inglês). Ele é um software livre e gratuito, com uma grande comunidade de usuários e documentação extensa e detalhada. O Git “gerencia a evolução de um conjunto de ficheiros - chamado repositório ou repo - de uma forma consciente e altamente estruturada” (Bryan, 2018, p. 2, tradução minha). Todas as mudanças são registradas (commits) assim como um conjunto de metadados para cada commit: identificação única, autoria, mensagem e data. Esses mecanismos e informações permitem a compreensão geral da história do desenvolvimento de um projeto (Kim et al., 2021, p. 657).

O Git compreende seus dados como “uma série de snapshots de um sistema de arquivos em miniatura”, ou seja, toda vez que você submete uma alteração ao repositório, o “Git basicamente tira uma fotografia de como todos os seus ficheiros são naquele momento e armazena uma referência para aquele snapshot” (Chacon e Straub, 2014, p. 15). Se um ficheiro não foi modificado, o Git não o armazenará novamente, apenas cria um link atualizado para ele, o que o torna mais leve e rápido. Essas características garantem a integridade do Git, visto que é impossível alterar o conteúdo de qualquer ficheiro ou diretório sem o Git saber (Chacon e Straub, 2014, p. 15). Praticamente todas essas operações acontecem localmente, minimizando problemas relativos à conexão com servidores, violação de dados e segurança.

Ao longo do artigo, apresento as principais funcionalidades do Git e como utilizá-las, assim como apresento boas práticas de documentação através das mensagens de commit. E concluo:

O uso consciente e sistemático do Git, apesar de sua curva de aprendizado mais acentuada, permite que pesquisadores e equipes possam trabalhar de forma segura e controlada, integrando ao processo de pesquisa/escrita os procedimentos metodológicos de documentação e registro de metadados e decisões tomadas. Ao mesmo tempo, garante a criação de uma linha do tempo de todo o processo, permitindo a recuperação das informações e restauração de ficheiros.

Entendo que com o Git no cotidiano de uma pesquisa, ganhamos tempo e tranquilidade para documentar, preservar e recuperar informações, assim como apresentar de forma transparente todas as nossas decisões e escolhas a qualquer momento.