Diretrizes para Revisores
O processo de revisão do Programming Historian em português é uma excelente forma de aprender novas competências técnicas e de se envolver com a comunidade das humanidades digitais. Fazemos todo o possível para garantir que os nossos revisores recebam crédito e reconhecimento pelo seu trabalho. Como os revisores contribuem directamente para melhorar significativamente as lições, eles podem ter orgulho que o seu trabalho irá ajudar milhares de leitores.
Estas directrizes destinam-se a ajudar os revisores a compreender o seu papel no processo editorial e a responder a perguntas comuns sobre como ser mais eficiente e eficaz com as suas revisões.
Conteúdos
Filosofia da Revisão
Consideramos o processo de revisão um componente integral de um esforço colaborativo, produtivo e sustentável para os académicos criarem recursos técnicos úteis para todos. Quando um tutorial entra no nosso fluxo editorial, trabalhamos em estreita colaboração com o autor e os revisores para maximizar o potencial e publicá-lo dentro de um período de tempo razoável.
Crítica Construtiva
Rever um tutorial não é simplesmente avaliar os seus méritos e falhas (embora seja importante fazê-lo também), mas ajudar a melhorar o tutorial em virtude de uma perspectiva externa. Pedimos que os revisores façam críticas justas e construtivas (e, claro, elogios) que ajudem a melhorar o tutorial para uma audiência de leitores ampla.
Transparência
Valorizamos muito a transparência no nosso processo de produção e revisão de lições. O nosso processo de revisão acontece no Github, onde as nossas lições estão hospedadas. Nomeadamente, nós utilizamos os recursos de comentários e de rastreamento de problemas do Github para acompanhar as sugestões e a forma como são tratadas e discutidas pelos autores e revisores. Isto ajuda a evitar que conversas importantes sejam esquecidas e se percam em discussões por e-mail.
Portanto, o trabalho como revisor - e a sua identidade - será totalmente visível para o autor. Os comentários devem envolver diretamente o autor e a lição, e não o revisor. Se em algum momento não tiver certeza do seu papel ou do que fazer a seguir, sinta-se à vontade para fazer uma pergunta e um editor responderá assim que puder.
Seguindo as ideias de investigação pública e de revisão aberta por pares, geralmente incentivamos as discussões a permanecer no GitHub, conforme descrito no fluxo de trabalho editorial. No entanto, queremos também que todos se sintam à vontade. Em alguns casos, uma conversa privada pode ser mais apropriada. Se sentir a necessidade de discutir um assunto relacionado a um tutorial ou relacionado à revisão, por favor, sinta-se à vontade para enviar um email diretamente para o editor designado, ou entrar em contato com o nosso mediador independente.
A menos que seja dada indicação contrária, o nome dos revisores estará na página da lição quando for publicada oficialmente e também estará listado na nossa página de colaboradores.
Abertura e Inclusão
O Programming Historian em português se dedica a prover um ambiente académico aberto que oferece aos participantes da comunidade a liberdade de examinar minuciosamente as ideias, fazer perguntas, fazer sugestões ou pedidos de esclarecimento. Insistimos em ter um espaço livre de assédio para todos os colaboradores do projeto, independentemente do género, identidade e expressão de género, orientação sexual, deficiência, aparência física, tamanho corporal, raça, idade ou religião ou experiência técnica. Não toleramos o assédio ou ataques ad hominem aos participantes da comunidade, de nenhuma forma. Os participantes que violem estas regras podem ser expulsos da comunidade, a critério do conselho editorial. Se alguém testemunhar ou sentir que foi vítima da atividade acima descrita, por favor contacte o nosso mediador independente. Obrigado por nos ajudar a criar um espaço seguro.
O que comentar
O estilo informal das lições do Programming Historian em português pode fazer com que estas pareçam enganosamente simples de escrever. De fato, escrever um bom tutorial é tão exigente, se não mais, do que qualquer outro tipo de escrita académica. Abaixo estão algumas perguntas comuns a ter em mente ao rever uma lição. Algumas serão mais relevantes do que outras, dependendo do tema, do público-alvo e da dificuldade do tutorial. É importante ressaltar que esta não é uma lista restritiva ou abrangente; não pedimos aos revisores que respondam a cada uma das perguntas, mas esperamos que possam fornecer alguma orientação geral.
Público-alvo
O Programming Historian em português se dirige a um público variado e com níveis de competência diferentes. Algumas lições são para iniciantes, outras são para aqueles consideravelmente mais confortáveis com conceitos e métodos técnicos, e outras ainda são dirigidas a historiadores digitais experientes que procuram resolver desafios técnicos difíceis. Aplaudimos essa diversidade!
Embora gostemos que cada uma das nossas lições tenha a marca pessoal do seu autor (ou tradutor), também queremos que cada lição individual permaneça com uma linguagem clara e homogénea. Mais especificamente, queremos que as explicações técnicas (e a dificuldade) permaneçam tão constantes quanto possível ao longo de toda a lição. Como revisor, é bastante útil observar as seções de um tutorial direcionadas a utilizadores tecnicamente avançados que parecem explicar excessivamente conceitos relativamente simples; o inverso também é verdadeiro: queremos evitar seções de tutoriais destinadas a iniciantes que não explicam adequadamente os conceitos fundamentais centrais ao tutorial. Algumas questões a considerar:
- O autor dirige-se a um tipo de leitor consistente ao longo da lição?
- Alguns conceitos ou passos são excessivamente explicados enquanto outros são poucos explicados?
- O público-alvo parece corresponder, pelo menos vagamente, ao de outras lições do Programming Historian em português? Em que medida é um novo público-alvo?
Preparação
- Quais os softwares / as linguagens de programação necessárias?
- Quais as competências prévias necessárias?
- Que familiaridade ou experiência é necessária?
- Que dados são necessários? O conjunto de dados está facilmente disponível?
Estrutura
- Existem objetivos de aprendizagem ou conjuntos de competências a aprender claramente definidos, listados no início da lição?
- Existem competências secundárias úteis a serem adquiridas / praticadas a partir da lição?
- As capturas de tela e outros diagramas ilustram etapas / pontos cruciais da lição?
- As seções e os títulos das seções são claros e guiam o leitor?
Benefícios
- O tutorial sugere se as ferramentas ou técnicas explicadas são úteis de uma maneira geral?
- O tutorial sugere como o leitor pode aplicar os conceitos (ou as etapas) da lição ao seu próprio trabalho?
Fluxo de Trabalho
- A lição está muito grande e deve ser dividida em lições menores?
- Existem pontos de interrupção lógicos ao longo da lição?
- Se conjuntos de dados são necessários, estão disponíveis para download ao longo da lição (ou diferentes versões dos mesmos, se o tutorial assim o exigir)?
Sustentabilidade
Para o aumentar a vida útil das nossas lições, os revisores do Programming Historian em português devem ter em mente as seguintes questões sobre sustentabilidade. Cada submissão é diferente e algumas destas questões podem não ser aplicáveis a todas as submissões. Tendo em conta o nível de dificuldade de cada lição e o público a que se destina, os revisores devem utilizar estas questões como diretrizes para garantir que as lições sejam tão sustentáveis quanto possível a partir da data de publicação.
- Todas as versões do software e as suas dependências estão listadas na submissão? Estes recursos estão nas versões mais recentes? Se a lição utiliza versões de software mais antigas, o autor indica o motivo?
- Se você tem experiência na metodologia ou ferramenta(s) específica(s) para a lição, a metodologia está atualizada?
- Quais são as fontes de dados para a submissão? Estão incluídas de uma forma que não dependam de uma hospedagem externa?
- Que outros tipos de links ou recursos são utilizados na lição? São atuais ou existem outros recursos mais recentes ou apropriados?
Integrando a lição no Programming Historian em português
- A lição baseia-se numa lição já existente e explica como?
- A lição está ligada a outras lições existentes e tem os links apropriados?
Submeter a revisão
Gerimos todos os comentários de revisão por pares através do GitHub. Quando uma nova lição estiver pronta para revisão, o editor fornecerá um link para a lição e um link para o fórum de discussão onde podem ser feitos comentários construtivos. Esta discussão é realizada no Github, um ambiente de codificação social livre. É preciso se inscrever numa conta gratuita do GitHub para publicar o comentário. Encorajamos que a discussão permaneça no Github, mas pode enviar um e-mail ao editor em particular ou entrar em contato com o nosso mediador independente.