Como fazer um tutorial?

Nós, da equipe Vida de Silício, apresentamos este documento como forma de demonstrar os principais pontos que devem ser observados pelos autores durante o processo de desenvolvimento de conteúdos para o portal.

Este material visa trazer algumas diretrizes de padronização para que todo conteúdo produzido obedeça certos requisitos de organização. Além disso, este também tem a função de nortear o autor no processo criação, por meio da execução de uma sequência predefinida passos.

É importante ter em mente de que, com esse padrão, conseguimos fazer um tutorial em uma linha de raciocínio didática. Ajuda a orientação tanto do autor durante a escrita como do leitor no momento do aprendizado.

Lembre-se que o objetivo do Portal Vida de silício é concentrar em um só lugar tutoriais de alta qualidade dos mais diversos assuntos. Tudo isso organizado de forma simples e intuitiva.

“Se quer ir rápido, vá sozinho. Se quer ir longe, vá acompanhado.”

Toda sugestão será bem vinda!

[toc]

Sobre qual assunto falar?

Você pode escrever sobre praticamente qualquer assunto ligado a robótica no portal Vida de Silício. Como queremos impactar o máximo de pessoas possíveis, a grande sacada é fazer conteúdos sobre assuntos que são de interesse geral.

Exemplos de temas:
  • Tutoriais sobre o básico de Raspberry pi
  • Tutorias Básicos de NodeMCU
  • Tutoriais de sensores e módulos com Arduino

Existem muitas outras plataformas, tais como: Freescale , MSP, Beaglebone, Orange Pi. Se você tiver conhecimento sobre qualquer uma delas, sua contribuição com certeza será bem vinda. A única recomendação é que sempre se comece com um tutorial de apresentação da plataforma trabalhada. Um tutorial no estilo:”O que é Arduino?”

Criando um tutorial no WordPress

Depois de criado sua conta como autor do site, você terá acesso exclusivo à área administrativa do Portal.  Iremos explicar a partir daqui como criar seu primeiro tutorial

Criando um post

O primeiro passo para que um determinado conteúdo seja publicado no portal Vida de Silício consiste no acesso do autor ao ambiente de desenvolvimento  adequado, utilizando o login e a senha previamente criados e cedidos pela nossa equipe.

Em seguida, deve-se localizar a opção Posts na barra de ferramentas localizada à esquerda da tela e posteriormente clicar em Adicionar novo.

Após a realização do procedimento anterior, o autor terá acesso à página em que poderá desenvolver o conteúdo desejado. Neste local, existem basicamente dois campos a serem preenchidos pelo mesmo: o título (lembre-se de escolher um que consiga expressar o conteúdo abordado de maneira clara) e o texto em si.

Em relação ao texto, torna-se necessário fazer uma ressalva, que consiste no fato de que o autor deve usar formatações diferentes para os tópicos e subtópicos existentes ao longo do conteúdo.

É importante resaltar que você precisa alternar a barra de ferramentas para que tenha acesso as configurações que usaremos para formatar o texto. Para isso clique no ícone “Alternar barra de ferramentas”

Como será visto posteriormente, o tutorial a ser desenvolvido possui basicamente três partes: Uma parte introdutória, uma parte de desenvolvimento e uma parte voltada para que o autor apresente um maior detalhamento sobre os elementos que constituem o projeto. Sendo assim, sempre que uma destas seções for iniciada, é necessário utilizar o Cabeçalho 1 para apresentar o título da mesma, no entanto, em relação às divisões internas de casa uma das partes citadas, utiliza-se o Cabeçalho 2 como título de cada subparte destas. Para as demais partes do texto, basta selecionar a opção Parágrafo.

Anexando imagens

Deve-se ressaltar que além dos elementos escritos, existe também a possibilidade de realizar a inclusão elementos gráficos no espaço reservado para o desenvolvimento. Para inserir, por exemplo, uma imagem no conteúdo que esta sendo produzido, basta que o autor clique no botão Adicionar mídia.

Em seguida, deve-se selecionar  imagem desejada (este procedimento pode ser feito arrastando a imagem para a tela ou clicando no botão Selecionar arquivos e escolhendo a mesma manualmente).

Apenas como uma observação, sugerimos que o autor não utilize legenda nas imagens, no entanto, deve-se salientar que é necessário que o significado de uma eventual imagem utilizada esteja condizente com o conteúdo apresentado.

Inserindo códigos

Assim como é possível anexar imagens ao conteúdo, pode-se também realizar a escrita de códigos de programação caso seja necessário. Para realizar este procedimento, deve-se clicar no seguinte ícone.

Em seguida, basta somente escrever o código no espaço adequado (não é necessário que o autor altere qualquer uma das configurações preestabelecidas apresentadas nesta janela) e clicar em OK. 

Será adiciona uma caixa com o código na área de edição do seu tutorial.

O código ficará assim quando postado:

//Exemplo de código 

// Função Setup void 
setup() { 
   pinMode(LED_BUILTIN, OUTPUT); 
} 

// Função Loop void 
loop() {
   digitalWrite(LED_BUILTIN, HIGH); // Liga o LED 
   delay(1000); // Espera 1 segundo 
   digitalWrite(LED_BUILTIN, LOW); // Desliga o LED 
   delay(1000); // Espera 1 segundo 
}

 

Inserindo partes expansíveis em seu tutorial

Caso queira, você pode criar partes expansíveis em seu tutorial tal como o exemplo abaixo.

Exemplo

Para usar isso em seu tutorial, você precisará usar da o seguinte código

Coloque aqui o conteúdo

Veja como ficou nesse tutorial:

Como o post deve está organizado?

Como forma de padronização, nós pedimos aos autores que dividam os conteúdos em algumas seções predeterminadas. Basicamente, um tutorial deve conter três partes, nas quais, a primeira delas deve ser voltada para introduzir o conteúdo para o leitor, a segunda corresponde ao desenvolvimento do projeto, enquanto a terceira faz explicação detalhada do funcionamento do mesmo.

  • Parte 1: O que será aprendido; (H1)
    • O que vamos aprender? (H2)
    • Contexto histórico ou Aplicação prática  (H2)
    • Introdução e Explicação sobre os componentes-chave  (H2)
  • Parte 2: Mão à obra – Exemplo;   (H1)
    • Componentes necessários  (H2)
    • Montando o projeto  (H2)
    • Conectando ao computador  (H2)
    • Programando  (H2)
    • Colocando para funcionar  (H2)
  • Parte 3: Entendendo a fundo – Explicação detalhada do projeto da parte 2 (H1)
    • Software (H2)
      • Divida sua explicação em subtítulos; (H3)
    • Hardware (Opcional) (H2)
      • Divida sua explicação em subtítulos; (H3)

No fim do Tutorial costumamos adicionar uma quarta parte com os seguintes tópicos:

  • Desafio (Opcional)
  • Fechamento

Sobre o uso dos cabeçalhos

Para organizar esse esqueleto de forma visivelmente agradável, usamos a divisão em cabeçalhos.  Dividimos o tutorial em três tipos de cabeçalhos

Cabeçalho 1 – Tópicos principais (H1) 

Esse cabeçalho precisa ser azul e no formato Oswald.

Cabeçalho 2 – Divisão dos tópicos principais (H2)

Esse cabeçalho só precisa ser preto

– Cabeçalho 3  – Subtítulos (H3)

Esse cabeçalho é preto e adicionamos um traço antes do titulo.

Veja que no tópico anterior adicionamos na frente de cada título e subtítulo as abreviações: H1, H2 e H3. Eles mostram quais as configurações de cabeçalhos a serem usados para da um deles.

A seguir, disponibilizamos um roteiro para que fique mais fácil seguir as diretrizes necessárias para a realização de um tutorial bem claro e didático para o leitor.

O que vamos aprender? (Aqui entra o título que responde essa pergunta)

(QUAL É O OBJETIVO DESSE ARTIGO/POST/CONTEÚDO/MATERIAL? OU DEIXAR SEM NADA PARA O AUTOR COMEÇAR JÁ COM O TEXTO?)

Este espaço está reservado para que o autor fale sobre o objetivo do projeto proposto, ou seja, sugerimos para o autor que elabore um ou dois pequenos parágrafos explicando sobre o que será desenvolvido e o que o leitor poderá aprender com a leitura do conteúdo em questão.

Esse primeiro paragrafo é muito importante para que o Google consiga saber do que se trata o projeto e que ele possa direcionar às pesquisas certas. Então sempre coloque os assuntos principais em negrito, tal como o nome do módulo.

Contexto Histórico e aplicação prática

Nesta seção, sugere-se que o autor elabore um pequeno conteúdo referente ao contexto histórico do assunto proposto, de modo que, através da apresentação do mesmo, o leitor possa compreender um pouco a importância do que está sendo tratado, além de adquirir uma noção básica sobre a aplicabilidade do projeto e por que aprender sobre o mesmo é interessante.

Introdução aos Componentes-chave

Em geral, a maioria dos tutoriais possuem algum módulo ou controlador que pode ser encarado como o elemento mais importante do projeto, portanto, entende-se que, para uma melhor didática e clareza é necessário que o autor descreva um ou mais parágrafos sobre o(s) mesmo(s). O objetivo desta seção consiste em criar um ambiente em que o leitor, caso não tenha um entendimento muito abrangente sobre o assunto que está sendo tratado, possa sentir-se confortável, seguro e interessado para aprender sobre o mesmo.

Foto do módulo ou componente que será explicado

Mãos à Obra – Desenvolvimento do projeto

Esta é a seção onde, de fato, ocorre o desenvolvimento do projeto em si. Sugerimos dividir esta seção em 5 partes para auxiliar na escrita do conteúdo proposto.

Componentes Necessários

Primeiramente, o autor deve listar os componentes que serão utilizados no desenvolvimento do projeto e também associá-los aos respectivos links existentes na loja. Veja o exemplo abaixo:

Nesta seção, pedimos que o autor faça o uso marcadores para listar os componentes utilizados. Para realizar este procedimento deve-se apenas clicar no ícone correspondente conforme a figura abaixo.

Montando o Projeto

Em seguida, é necessário que o autor elabore uma imagem clara e didática do circuito utilizando o Fritzing (http://fritzing.org/home/).

Aqui é legal colocar uma foto do projeto montado depois do esquemático, caso seja possível, para que o leitor veja a montagem na prática.

Conectando o Arduino no Computador

Neste ponto, o autor deve lembrar ao leitor como configurar a IDE do Arduino para receber o código que será apresentado posteriormente. Este passo é necessário pois muitas vezes ocorrem erros ao carregar o programa no Arduino em virtude de uma configuração inadequada da interface utilizada. Sugerimos o uso do seguinte texto padrão:

Conecte seu Arduino ao computador e abra a IDE Arduino.

Antes de carregar um programa, você precisa selecionar qual porta você deseja usar para fazer carregar o programa no Arduino (upload). Dentro do Arduino IDE, clique no menu Ferramentas (tools) e abra o submenu Porta(Port). Clique na porta que seu Arduino está conectado, tal como COM3 ou COM4. Geralmente aparece o nome da placa Arduino : “COM3 (Arduino/Genuino Uno)”.

Você também precisa garantir que o tipo de placa apropriado está selecionado em Ferramentas(Tools) no submenu Placa (Board).

Programando

Esta seção é dedicada ao código da aplicação que está sendo desenvolvida neste tutorial.

– Biblioteca (Apenas se for usada alguma biblioteca)

Caso o autor tenha usado uma biblioteca é importante mostrar onde baixa-la e se possível como instala-la.

– Código do Projeto

Aqui basta que o autor coloque o código inteiro, comentado e de maneira bem organizada visualmente pois isso facilita para o leitor que não tem muita intimidade com a linguagem de programação utilizada.

É interessante escrever algo como:

“Segue o código a ser usado no exemplo”

// Programa Exemplo

uint32_t referencia = 0;
uint32_t tempoAtual;
void setup() {
pinMode(13,OUTPUT); // Configura o pino 13 (LED) como saída
}
 
void loop()
{
     tempoAtual = millis(); // Captura o tempo atual
// Verifica se já se passaram 1 segundo (1000 milissegundos)
// desde a última vez em que o LED foi invertido
     if(tempoAtual - referencia >= 1000) {
        // Se sim, inverte o LED e atualiza a referencia
        digitalWrite(13,!digitalRead(13));
        referencia = millis();
     }
}

Colocando para Funcionar

Aqui, sugerimos que o autor coloque uma foto do circuito montado fisicamente, um gif, ou até mesmo um pequeno vídeo, demonstrando a aplicação em funcionamento.

Entendendo a fundo

Esta é a terceira parte do tutorial que está sendo desenvolvido. Aqui, o autor deve elaborar duas seções para que possa explicar de maneira mais detalhada, tudo o que acontece por trás dos passos realizados anteriormente, ou seja, pede-se ao autor  que elabore um conteúdo teórico que explique o funcionamento do hardware e também que realize a análise código que foi inserido no Arduino, porém, com um nível maior de detalhamento.

Aqui colocamos a explicação do software antes do Hardware, mas você pode explicar na ordem que preferir.

Software (Importante)

Aqui o autor precisa explicar os comandos usados ao longo do projeto de forma a explicar ao leitor a função de cada comando visando o melhor entendimento.

É importante dividir a explicação em subtítulos tais como o abaixo:

– Declarando biblioteca

Exemplo de explicação

#include <Wire.h>
#include <LiquidCrystal_I2C.h>

– Função digitalRead()

Explicação exemplo.

estadoSensor = digitalRead(3);

Hardware (Opcional)

Aqui o autor pode explicar conceitos importantes sobre o Hardware tais como propriedades físicas ou como ele funciona.

Aqui vale também a divisão em subtítulos.

Desafio (OPCIONAL)

Caso o autor deseje, pode-se propor um desafio relacionado ao assunto tratado no conteúdo desenvolvido.

Fechamento

Para finalizar o tutorial, basta que o autor escreva um parágrafo de conclusão sobre o assunto e também peça ao leitor que não deixe de fazer seus elogios, críticas e sugestões sobre o conteúdo em questão. Além disso, também é importante abrir o espaço para que o leitor possa fazer perguntas e tirar as suas dúvidas.

Exemplos de tutoriais

Este foi o modelo referente à estrutura que deve ser seguida na elaboração de tutoriais. Acreditamos que, de acordo com esta proposta, seja possível produzir materiais de ótima qualidade e de fácil entendimento para o leitor.

Recomendamos que consulte alguns tutoriais para verificar essa organização:

Como dito no inicio desse tutorial, esse padrão visa o melhor entendimento de quem ler mas também visa facilitar a vida de quem escreve criando uma linha de raciocínio fácil de ser seguida. Caso tenha uma sugestão de como melhorá-la, ficaremos contentes e te ouvir.

Finalizando o conteúdo

Após a finalização da elaboração do conteúdo, o autor deve enviar o mesmo para revisão e avisar a equipe Vida de Silício, por e-mail, que o material está concluído.

Respondendo aos comentários

Recomendamos que o autor fique atento aos comentários e sempre que possível responda as dúvidas dos leitores nos seus respectivos conteúdos. Assim você gerará uma interação bacana com seus leitores e ainda ajudará pessoas que provavelmente possuem a mesma dúvida.

Caso seja necessário, você pode utilizar links externos nas respostas, desde que não sejam de concorrentes diretos da loja Vida de Silício.