Estamos felizes em poder construir esta comunidade e abrir um canal direto para escritores compartilharem seus conhecimentos sobre administração e desenvolvimento de servidores na nuvem. Então, para mais consistência e qualidade para estes artigos, desenvolvemos algumas diretrizes escritas a seguir.

Separamos nossas diretrizes em 4 pilares para garantir uma boa prática de redação dentro da nossa comunidade.

  1. Estrutura: é o layout e a organização de qualquer artigo escrito neste canal.
  2. Conteúdo: trata de como devemos escrever e explicar os tutoriais.
  3. Formato: Markdown.
  4. Terminologia: Algumas dicas sobre terminologia técnica comum.

Para escrever você devem ler estas diretrizes na íntegra, pois serão necessárias para que o artigo seja publicado rapidamente. Suas diretrizes devem ser consultadas sempre que houver uma duvida.

Estrutura

Todos os tutoriais precisam de uma estrutura com as seguintes seções:

  1. Título
  2. Introdução
  3. Metas (opcional)
  4. Pré-requisitos
  5. Etapas (1 ... n)
  6. Conclusão

Para um início rápido, criamos um modelo de artigo com essa estrutura no Markdown. Para obter mais informações sobre as convenções de formatação, vá para nossa seção Formato.

Título

O título deve ser um grande resumo sobre o que o seu leitor realizará no final do tutorial. Mais do que isso, seu título deve ser pesquisável "com palavras chavest" de acordo com as necessidades do leitor.

Um título típico segue este formato: Como "a tarefa a ser realizada" com o "Software" na "Distro".

Inclua o objetivo principal do tutorial no título, não apenas as ferramentas que o leitor usará para realizar o seu passo a passo.

Exemplo: Se seu objetivo é instalar um servidor Git, se você colocar o objetivo será mais informativo. E então poderíamos ter um título como este "Como instalar e configurar um servidor Git com GitLab no Ubuntu 18.04"

Introdução

A introdução deve ser a primeira seção de cada tutorial. Resume em 1 a 3 parágrafos as seguintes questões:

  1. Qual é o objetivo principal do tutorial? O que o leitor realizará se o seguir?
  2. Quais softwares estão envolvidos e o que cada componente faz?
  3. Quais são os benefícios de usar este software específico para esse objetivo?
  4. Por que o leitor deve seguir este tutorial?

Metas

Alguns tutoriais realizam um objetivo principal, mas precisam explicar alguns objetivos secundários para alcançá-lo com sucesso. Você só deve usar esta seção neste caso. Um exemplo de uso é quando você precisa configurar vários servidores para completar uma arquitetura ou o objetivo principal é complicado o suficiente para ser explicado com apenas um tipo de configuração.

Pré-requisitos

Pré-requisitos é a seção que especifica o que o leitor deve ter ou fazer antes de seguir o tutorial. Basicamente, é uma lista de verificação de links para um tutorial existente que cobre o conteúdo necessário.

É aí que definimos coisas como:

  1. Número de instâncias.
  2. Recursos necessários (memória, disco, VCPus, IPv4, firewall)
  3. Distribuição.
  4. Dependências.
  5. Configuração inicial do servidor.
  6. Configurações de DNS.
  7. Certificados SSL.

Lembre-se de testar e seguir todos os tutoriais de pré-requisito exatamente como escritos, para que todos usem o mesmo ponto de partida. Se você alterar uma variável ou concluir uma etapa opcional de um dos pré-requisitos, certifique-se de observar isso.

Existem bons exemplos de pré-requisitos nesses tutoriais:

Passos

A parte das etapas é onde você descreverá o que o leitor precisa fazer.

Comece uma etapa com uma introdução que descreve o que a etapa cobre e que papel ela desempenha para atingir o objetivo principal.

Conclua cada etapa com uma frase que descreva o que o leitor realizou e para onde vai a seguir. Evite repetir o título da etapa e evite iniciar ou terminar etapas com instruções, comandos ou saída sem contexto.

Sempre coloque os comandos em sua própria linha e bloco de código e nunca se esqueça de descrever sua finalidade. Da mesma forma, sempre introduza um arquivo ou script descrevendo sua finalidade geral e, em seguida, explique todas as alterações que o leitor fará no arquivo. Essas explicações são importantes para permitir que os leitores personalizem, atualizem e entendam como agir com possíveis soluções de problemas.

Conclusão

A Conclusão deve resumir o que o leitor realizou seguindo seu tutorial. Também deve descrever o que o leitor pode fazer a seguir. Podem ser outras configurações que eles possam fazer, links para outros tutoriais desta comunidade ou uma dica para que explorem mais conhecimentos sobre o assunto.

Conteúdo

O conteúdo escrito em nossos tutoriais deve ser:

Claro e objetivo

Nossos tutoriais devem ser escritos de forma clara, detalhada, mas não cansativa.

Por claro e detalhado, significa não suposição sobre o conhecimento do leitor. Para cada comando necessário para fazer a configuração correta, precisamos escrever explicitamente o comando e explicar seu propósito.

De forma não cansativa, significa ser objetivo nas explicações e não fugir do assunto da etapa.

Tecnicamente e correto

Todos os nossos tutoriais devem ser testados em novas instâncias para garantir que funcionam. Qualquer comando deve ser explicado tecnicamente com opções e sinalizadores necessários para a configuração correta.

Seja prático

Qualquer tutorial escrito nesta comunidade deve ter um conteúdo prático. Uma vez que o leitor conclui todas as etapas, ele deve configurar um ambiente utilizável ou um exemplo. Isso significa que o artigo deve cobrir o assunto por completo e um link para outro artigo para configuração de pré-requisitos, se necessário.

Os escritores não devem enviar leitores para fora do site para coletar informações que possam ser adicionadas ao artigo.

O formal não é hostil

Por causa do conteúdo técnico, você deve usar um tom formal. Isso significa que você pode ser gentil e amigável, mas evitar piadas, memes ou gírias. Além disso, não usamos a primeira pessoa do singular, como "eu acho" ou "eu fiz". Em vez disso, use a primeira pessoa do plural ("Devemos fazer"), a segunda pessoa ("Você fará") ou mesmo a terceira pessoa ("Deve funcionar direito").

Use referências

Não se esqueça de sempre usar backlinks como referência em seu conteúdo. Aqui está uma lista de links que podem ser usados como referências.

Formato

Os tutoriais da LetsCloud estão no formato de linguagem de marcação Markdown. Há um guia Markdown aqui em nossa comunidade, se você não estiver familiarizado com ele.

Cabeçalhos

Cada seção deve corresponder a um cabeçalho. O título principal deve ser inserido no campo Título. Isso converterá o título no cabeçalho # H1 de seu artigo. A introdução deve ser um cabeçalho ### H3 e os objetivos, pré-requisitos, etapas e uma conclusão devem ter cabeçalhos # h2.

Os tutoriais procedimentais devem incluir números em seus cabeçalhos de etapas e usar o gerúndio. Ex .: Instalando o Apache.

Basta usar os sub cabeçalhos ### H3 e #### H4 se houver dois ou mais cabeçalhos desse nível na etapa. Em outro lugar, tente adicionar várias etapas.

Ênfase

O texto em negrito deve ser usado para:

  1. Hostnames e usernames, como ** banco_de_dados_1 ** ou ** rick **
  2. Listas de termos
  3. Ênfase ao mudar o contexto de um comando, como mudar para um novo servidor ou usuário

Faça isso em torno do termo em nosso destaque Markdown ** Este é o meu termo ** para usar texto em negrito.

Itálico só deve ser usado na introdução de termos técnicos. Por exemplo, usaremos este seridor como um cluster de banco de dados.

Faça isso em torno do termo em nosso destaque Markdown * Este é o meu termo * para usar itálico.

A formatação de código in-line deve ser usada para:

Command names, eg.: apt-get Optional commands Package names, eg.: php-all-dev File names and paths, eg.: ~/.ssh/authorized_keys URLs, eg.: https://letscloud.io Ports, eg.: 80:8080 Key commands, which should be in ALL CAPS and use a plus symbol, +, if keys need to be pressed simultaneously, like ENTER or CTRL+V

Faça isso em torno do termo em nosso destaque Markdown This is my term para usar a formatação de código em linha

Blocos de Código

O bloco de código deve ser usado sempre:

  1. Para mostrar os comandos a serem executados pelo leitor.
  2. Saída do terminal.
  3. Diálogos interativos em texto.
  4. Arquivos e scripts.

Para arquivos, geralmente é melhor mostrar apenas a seção que será alterada.

Para escrever um bloco de código, use nossos prefixos Markdown personalizados para qualquer comando. Veja abaixo alguns exemplos:

​```command
   sudo apt-get upgrade
​```
​```super_user
   service php7.1-fpm restart
​```
​```custom_prefix(mysql>)
   FLUSH PRIVILEGES;
​```

Será renderizado assim:

$
sudo apt-get upgrade
#
service php7.1-fpm restart
mysql>
FLUSH PRIVILEGES;

Etiquetas de bloco de código

Nosso Mark Down também inclui rótulos e rótulos secundários adicionando os comandos como no exemplo abaixo:

::::file
:::title
labeltext.txt
:::
user       www www;  ## Default: nobody
worker_processes  5;  ## Default: 1
error_log  logs/error.log;
pid        logs/nginx.pid;
worker_rlimit_nofile 8192;
::::
​````super_user
:::output
156 packages can be updated.
65 updates are security updates.
:::
cd /home/
​````

Os rótulos são úteis para marcar o conteúdo de um arquivo com um nome de arquivo. Veja o exemplo abaixo:

labeltext.txt

user www www; ## Default: nobody worker_processes 5; ## Default: 1 error_log logs/error.log; pid logs/nginx.pid; worker_rlimit_nofile 8192;

Os rótulos secundários são úteis para marcar a saída do terminal. Veja o exemplo abaixo:

  #156 packages can be updated.
65 updates are security updates.
cd /home/

Informação e Aviso

Use o bloco de informações Markdown para enfatizar um texto muito importante. Veja abaixo alguns exemplos:

::: info
teste
:::
::: warning
teste 2
:::

E aqui está o resultado renderizado:

Dica: aqui vai uma dica.

Cuidado: isso reiniciará sua instância.

Variáveis em destaque

Destaque todos os itens que precisam ser alterados pelo leitor, como URLs, nomes de usuário ou configurações em arquivos de configuração. Faça isso em torno do termo em nosso destaque Markdown ==This is my term==. Como não é possível destacar várias linhas, você precisará usar o Markdown de destaque para cada linha do termo destacado.

Para fazer referência a uma variável dentro de uma formatação de código in-line, você deve usar os dois estilos de formatação. Consulte seus destaques em seus tutoriais usando linguagem como "... destacado acima ..." e evite usar a cor específica como "... destacado em vermelho abaixo ..."

Imagens e ativos

As imagens são realmente úteis para ilustrar ações ou resultados em uma etapa. Pode ser usado pelos seguintes motivos:

  1. Diagramas de configuração do servidor.
  2. Capturas de tela da GUIs.
  3. Diálogos interativos.

As imagens não devem ser utilizadas para ilustrar qualquer referência textual como comandos, conteúdo de arquivo, pois pode ser copiado e colado como texto dentro do artigo.

Para incluir imagens, siga estas diretrizes:

  1. Use o formato de arquivo .png
  2. A imagem deve ser informativa e legível ao contexto.
  3. Faça a imagem com pelo menos 900px por 500px.

Abaixo, você vê o código Markdown para incluir imagens em seu tutorial:

![Texto alternativo para leitores de tela](http://letscloud.io/your_image_url)

Example Image

Terminologia

Usuários, nomes de host e domínios

Escolha algo descritivo e útil para o leitor. Para nomes de usuário, você pode usar nomes como rick ou ana.

Para nomes de host, você pode se referir a your_server_ip e para configurações de vários servidores, você pode usar algo como wordpress_server e wordpress_database_server.

Para domínios, você pode consultar example.com e para configurações de vários servidores, você pode usar algo como first.example.com e second.example.com ou algo mais descritivo.

Endereços IP e URLs

Use sempre your_server_ip, com formatação de código em linha e como destaque de variável e para vários endereços IPs, use nomes como first_private_ip e second_private_ip.

Para endereços IP mais realistas, use os endereçoss 203.0.113.0/24 para endereços públicos e 198.51.100.0/24 para endereços privados. Ambos são reservados para documentação de acordo com RFC-5737.

Para URLs, você deve usar o estilo Markdown padrão, como https://letscloud.io mas os URLs que contêm uma variável que o leitor precisa personalizar devem usar a formatação de código em linha com a variável destacada. O padrão é usar example.com like https://example.com:8080/simple/ ou https://your_server_ip/.

Software e Projeto

Use a capitalização do site oficial do nome do software ou projeto. Se não houver consistência de uso no site oficial, tente escolher uma capitalização para todo o tutorial.

Ex .: "O WordPress pode ser instalado no wordpress_server" - Certo. "O Wordpress pode ser instalado no wordpress_server" - Errado.

Related Articles

Read more about: Operating SystemControl PanelsNetwork & ArchitetureDevelopmentData Management