Pode fazer uma doação ao Programming Historian

Directrizes para Autores

Uma mulher numa mesa escrevendo.

Etapa 1: Propor uma nova lição

Etapa 2: Escrever e formatar uma nova lição

Etapa 3: Submeter uma nova lição

Estas directrizes foram desenvolvidas para ajudar a entender o processo de criação de um tutorial para o Programming Historian em português. Estão incluídos detalhes práticos e teóricos do processo de escrita do tutorial, bem como a indicação do fluxo de trabalho e do processo de revisão por pares. Se a qualquer momento não estiver seguro, basta enviar um email ao editor Daniel Alves.

Etapa 1: Propor uma nova lição

Procuramos lições relevantes para as Humanidades sobre um problema ou processo que sejam sustentáveis a longo prazo e dirigidos a um público geral, com qualquer nível de aptidão técnica e experiência. O âmbito e extensão da lição devem ser adequados à complexidade da tarefa, mas não devem ter mais de 8.000 palavras (incluindo códigos). Lições mais curtas são bem-vindas. Lições mais longas podem precisar de ser divididas.

Se tem uma ideia para uma nova lição preencha o formulário de proposta de lição e envie para Daniel Alves.

Para ter uma ideia do que publicamos consulte as lições publicadas, leia as nossas orientações para revisores ou navegue pelas lições em desenvolvimento. Por favor, reserve um momento para verificar o nosso documento de Concordância de Lições para ver quais os métodos já abordados nas nossas lições publicadas ou futuras.

Se a sua proposta for aceite, um editor criará uma página “Proposta” no nosso website de submissões com o título da lição, mesmo que seja apenas um rascunho, e com os objetivos propostos. Isto serve para acompanhar o trabalho em andamento. Para garantir a publicação em tempo útil, os autores devem enviar a sua proposta de lição no prazo de 90 dias.

Durante este período, o seu ponto de contato será o editor-chefe ou um editor nomeado.

Etapa 2: Escrever e formatar uma nova lição

Estas directrizes estabelecem um conjunto de regras para os autores utilizarem na criação ou tradução de lições para o Programming Historian em português. Ao utilizá-lo, os autores nos ajudarão a garantir que o conteúdo é consistente e acessível.

Estas estão organizadas em três seções que devem ser lidas antes e depois de escrever a lição:

A. Estilo e público

Esta primeira seção trata de questões gerais sobre o estilo, que ajudarão a tomar decisões que tenham em conta as necessidades do público e dos editores. Temos informações básicas sobre o estilo e o tom da lição, acesso aberto e valores de código aberto, informações sobre como escrever para um público geral, sustentabilidade das lições e escolhas inteligentes sobre as fontes de dados a utilizar. Leia esta seção quando planejar a lição e, novamente, antes de a enviar para garantir que cumpre os requisitos.

Idioma e estilo

Código aberto, Acesso aberto

O Programming Historian em português está comprometido com os valores de código aberto. Todas as lições devem usar linguagens de programação e softwares livres sempre que possível. O objetivo é minimizar os custos e permitir aumentar a participação o máximo possível.

Depois da lição ser aceite, o autor deve concordar com a sua publicação sob uma licença Creative Commons “CC-BY”.

Escrever para um público geral

Os leitores do Programming historian vivem em todo o mundo. Os autores podem e devem tomar medidas para escrever a lição de forma acessível para o maior número de pessoas possível. Siga estas directrizes gerais:

Escrita sustentável

O Programming historian em português publica lições que estarão disponíveis a longo prazo e que sejam sustentáveis. Por favor, siga estas directrizes de sustentabilidade ao escrever:

Os autores devem consultar a política de remoção das lições para obter informações sobre como a equipe editorial administra as lições que se tornam desatualizadas.

B. Directrizes específicas de estilo

Esta segunda seção é sobre questões mais específicas de estilo de escrita, tais como quais palavras usar, como utilizar a pontuação ou que formato adotar para datas ou números. Leia esta seção antes e depois de escrever seu texto.

Datas e Tempo

Números

Cabeçalhos

Os cabeçalhos não devem conter fontes de código embutido ou formatação de estilo como negrito ou itálico. Devem sempre preceder imediatamente o corpo do texto. Não coloque a seguir ao título um aviso ou outro título sem antes inserir uma nota introdutória.

Listas

Normalmente, utilizamos listas numeradas e listas com marcadores. Os itens das listas são limitados a frases. Devem ser tratados como itens separados, sem pontuação ou conjunções.

NÃO faz parte do estilo:

Faz parte do estilo:

Ou:

  1. Aqui está um item
  2. Aqui está outro item
  3. Aqui está o item final

Pontuação

Maiúsculas

A orientação é que seja utilizada com moderação no texto em prosa. Regras específicas:

Referências

C. Directrizes de formatação

Esta seção final aborda questões de formatação para a submissão. Leia esta seção antes e depois de escrever o seu rascunho. Se errar alguns destes elementos, poderá corrigi-los quando publicarmos uma visualização online da lição no início do processo de revisão por pares.

Escrever em Markdown

Todas as lições devem ser escritas em Markdown. Existe um template para as lições.

Markdown é uma linguagem de marcação que é mais fácil de trabalhar num editor de texto. O MS Word e o Open Office NÃO são editores de texto e devem ser evitados. Recomendamos Atom, TextWrangler, TextEdit, MacDown ou Notepad++. Para uma primeira introdução à formatação do Markdown, consultar Introdução ao Markdown, ou uma explicação mais breve em Guia de Markdown do GitHub.

A lição deve ser guardada no formato .md. O nome do ficheiro da lição torna-se parte do URL da lição. Portanto, deve ser nomeado de acordo com as seguintes regras:

Negrito, itálico e sublinhado

Para garantir coerência entre as lições, siga as seguintes diretrizes de formatação de texto:

Negrito

Itálico

Sublinhado

Alertas e avisos

Se deseja incluir uma nota ou um aviso para os leitores, é possível separá-lo do texto principal:

<div class="alert alert-warning">
  Certifique-se de seguir as instruções cuidadosamente!
</div>

Figuras e imagens

As imagens podem ajudar os leitores a entender os passos da lição, mas não devem ser usadas como decoração. Se desejar usar imagens na sua lição, identifique-as sequencialmente como LESSON-NAME1.jpg, LESSON-NAME2.jpg, etc. Refira as imagens no texto como “Figura 1”, “Figura 2”, e assim por diante. Todas as figuras devem vir com uma legenda concisa e notas finais, quando apropriado. A licença legal para publicar qualquer imagem tem de estar assegurada.

Os ficheiros devem ser compatíveis com a web, preferencialmente .png ou .jpg, e devem ter um máximo de 840px no lado mais longo. Isso é especialmente importante para leitores de países com velocidades mais lentas de Internet.

As imagens devem ser guardadas numa pasta com o mesmo nome .md da lição. Quando submeter a sua lição o editor atribuído poderá ajudá-lo a enviar as imagens.

Para inserir uma imagem no seu texto, use o seguinte formato:

{% include figure.html filename="NOME-DO-FICHEIRO-DE-IMAGEM" caption="A LEGENDA USANDO \"BARRAS\" PARA SALTAR ASPAS INTERNAS" %}

Notar que as aspas da legenda devem ser limitadas por uma barra invertida, como no exemplo acima. As imagens podem não aparecer nas pré-visualizações da lição, mas o editor tem a missão de garantir que sejam renderizadas corretamente quando a lição for publicada.

Exemplos de código

As linhas de código devem ser formatadas para distingui-las claramente do texto em prosa:

Eles ficarão assim

e assim respectivamente.

– Recomendamos estas práticas ao escrever o código:

Em JavaScript:

abstract, arguments, await, Boolean, break, byte, case, catch, char, class, const, continue, debugger, default, delete, do, double, else, enum, eval, export, extends, false, final, finally, float, for, function, goto, if, implements, import, in, instanceof, int, interface, let, long, native, new, null, package, private, protected, public, return, short, static, super, switch, synchronized, this, throw, throws, transient, true, try, typeof, var, void, volatile, while, with, yield.

Em Python 2:

and, as, assert, break, class, continue, def, del, elif, else, except, exec, finally, for, from, global, if, import, in, is, lambda, not, or, pass, print, raise, return, try, while, with, yield.

Em Python 3:

and, as, assert, break, class, continue, def, del, elif, else, except, False, finally, for, from, global, if, import, in, is, lambda, nonlocal, None, not, or, pass, raise, return, True, try, while, with, yield.

Em R:

break, else, for, FALSE, function, if, in, Inf, NA, NA_character_, NA_complex_, NA_integer_, NA_real_, NaN, next, NULL, repeat, TRUE, while.

Etapa 3: submeter uma nova lição

Verifique se o ficheiro da lição está de acordo com as especificações acima. Quando terminado, é altamente recomendável pedir a pelo menos duas pessoas para ler a lição e experimentar o tutorial, para dar feedback e garantir que é entendido por todos. Desta maneira ajuda os revisores a concentrarem-se em ajudá-lo a produzir uma lição tão consistente quanto possível.

Se a lição está pronta a submeter, segue-se a revisão por pares. As submissões são feitas enviando materiais por e-mail para o editor, para que ele possa carregá-los no nosso site de revisão por pares no Github.

  1. Obter acesso: crie uma conta gratuita. Envie o nome de usuário Github para o editor, que dará acesso de upload ao nosso site de submissões. Informe o editor do nome do ficheiro da lição e se há imagens ou ficheiros de dados que acompanhem o tutorial. O autor não fará o upload inicial para o GitHub, mas precisará de acesso para postar revisões subsequentes.
  2. Preparar os materiais: se a lição incluir imagens, certificar-se de que todos os ficheiros estão nomeados de acordo com as convenções de nomenclatura especificadas acima. Essas imagens devem ser enviadas numa única pasta compactada. Se a lição incluir ficheiros de dados, estes devem ser enviados noutra pasta compactada.
  3. Enviar um e-mail ao editor: informe o editor de que está pronto para enviar a lição. Este e-mail deve incluir o ficheiro da lição, bem como as pastas de imagens e recursos, se aplicável.
  4. Juntar-se à conversa: o editor irá enviar os ficheiros para o nosso diretório de submissões e fazer as alterações iniciais necessárias. O editor abrirá também um ticket de revisão para a lição.
  5. Fazer revisões: o upload da lição inicial será realizado pelo editor designado, mas o processo editorial exigirá que o autor faça outras alterações. Todas as revisões subsequentes devem ser feitas pelo autor diretamente nos ficheiros do nosso repositório de submissões para garantir que se esteja a trabalhar com a versão mais recente do ficheiro da lição.

O processo de revisão por pares

Depois do editor verificar se os ficheiros estão carregados e formatados da forma correta, será enviado um link para a pré-visualização da lição, onde quaisquer erros de formatação serão evidentes e ainda podem ser corrigidos.

Todo o processo de revisão por pares estará registado num “ticket do Github”, que funciona como um quadro de mensagens de discussão aberta. Esteja ciente que o processo de revisão é feito em público e permanece disponível como um registo permanente da revisão por pares. Se houver alguma dúvida ou preferir uma revisão fechada, entre em contato com o editor.

O processo de revisão por pares normalmente tem três etapas:

1) O editor da lição irá ler e testar a lição cuidadosamente, fornecendo uma primeira ronda de feedback a que é necessário responder. O objetivo é garantir que a lição atende às necessidades dos leitores do Programming Historian, e que os revisores externos recebem uma lição que funciona. Normalmente tem um mês para responder a esta primeira revisão.

2) O editor abrirá a lição para a revisão formal por pares. Serão nomeados dois revisores convidados pelo editor, mas a comunidade também é convidada a participar se quiser. Geralmente, é pedido que os revisores dêem os seus comentários dentro de um mês, mas às vezes imprevistos podem levar a atrasos. O editor deve deixar claro que não deverá responder às revisões até que as duas estejam publicadas e o editor já tenha feito um resumo com instruções claras sobre como avançar. Às vezes, pode incluir a sugestão para repensar substancialmente a lição, outras vezes, será uma questão de fazer pequenas alterações. Dependendo dos comentários da revisão por pares e da natureza dos problemas levantados, pode ser preciso rever o tutorial mais do que uma vez, mas o editor tem como missão garantir que o caminho para a publicação seja claro e bem definido. A qualquer momento pode pedir para sair do processo de revisão, se assim o desejar.

3) Quando o editor e revisores estiverem satisfeitos com a lição, o editor recomendará a publicação ao Editor Chefe, que irá ler e garantir que corresponde às Directrizes para Autores e aos padrões do Programming Historian. Em alguns casos, podem haver revisões adicionais ou edições nesta fase para alinhar a peça aos padrões de publicação. Se o Editor Chefe estiver satisfeito com a lição, ela será copiada para o site online. Quando isto acontecer o editor irá comunicar se qualquer informação adicional for necessária nesta fase.

Pode ser útil ler as directrizes para editores, que apresentam mais detalhes sobre todo o processo editorial.

Se, a qualquer momento, tiver dúvidas do seu papel ou o que fazer a seguir, basta publicar a pergunta na discussão da revisão por pares. Qualquer um dos nossos editores responderá assim que possível. A equipe esforça-se por responder a todas as perguntas dentro de poucos dias.

O que acontece depois da lição ser publicada?

Ocasionalmente, recebemos feedback de usuários que encontraram um erro ao concluir uma de nossas lições. Se isso acontecer, o/a nosso/a Assistente de Publicação abrirá um ticket no GitHub e, em seguida, realizará uma avaliação para confirmar se o erro relatado representa um problema causado pelo usuário (editar o código da lição ou alterar o seu conjunto de dados, por exemplo) ou um problema dentro da lição em si. Neste último caso, o/a nosso/a Assistente de Publicação testará novamente a(s) parte(s) relevante(s) da lição e fará pesquisas para identificar uma correção. Como parte deste processo de manutenção da lição, podemos contatá-lo juntamente com outros membros da equipe do Programming Historian para pedir conselhos. Caso nenhuma correção seja encontrada, proporemos adicionar um aviso à lição explicando que alguns usuários podem encontrar um erro. Sempre que possível, o aviso deve incluir links para leituras adicionais, permitindo que os usuários identifiquem eles próprios uma solução.

Responsabilidade da equipe

A equipe de voluntários trabalha intensamente para fazer uma revisão rigorosa, académica e eficiente para aos autores. No entanto, reconhecemos que há momentos em que podemos ficar abaixo das expectativas. Queremos que os autores se sintam à vontade para nos ajudar a manter os nossos padrões elevados. Se, por qualquer motivo, sentir que foi tratado injustamente, está insatisfeito ou confuso com o processo, se o processo foi adiado desnecessariamente, ou um revisor foi rude e o editor não respondeu de acordo, ou mesmo se tiver qualquer outra preocupação, chame a atenção da equipe para que se possa resolver rapidamente.

Apresentar uma questão NÃO afetará o resultado da revisão por pares - mesmo que ainda esteja a decorrer.

Para apresentar uma preocupação, basta entrar em contato com uma das seguintes partes, escolhendo com quem se sentir mais confortável em abordar a questão:

Esperamos que não se encontre infeliz com nenhuma situação, mas, se for o caso, agradecemos que nos ajude a melhorar.

Este guia de estilo foi criado com o apoio da Escola de Humanidades da Universidade de Hertfordshire.