Dicas para fazer um bom tutorial
Os tutoriais é uma das coisas mais importantes numa comunidade de programação , pois permitem a partilha de conhecimentos entre as pessoas mais vividas e menos vividas, por isso deve existir algumas regras básicas , ou dicas para que essa aprendizagem não se torne em um problema .
O meu primeiro tópico foi um tutorial e desde ai nõ parei, no inicio nгo tinha uma grande estrutura entгo ao longo do tempo fui consecutivo e queria por fazer tutoriais que sгo reconhecidos aqui na board.
Para fazer um bom tutorial deve-se ter a noзгo do que se estб a ensinar , ou seja, nуs devemos ter a certeza queo nosso conhecimento é correto e não errado , claro que algumas vezes isso pode acontecer por isso que existem como tais críticas-construtivas , essas críticas servem para nуs aprender e melhorar.
Eu penso que muita gente ao fazer tutoriais acha que apresentar um código é o mais fundamental , mas isso é errado, a ideia do tutorial é compartilhar o conhecimento e não o código, dessa forma o código é apenas um exemplo ou um complemento da nossa teoria , digamos que ele é a parte experimental do conhecimento, mas não podemos ignorar pois a experiência irá verificar a nossa teoria.
Saindo um pouco da filosofia e voltando ao assunto, existem algumas coisasfundamentais e a primeira delas é saber escrever , pois a língua é o nosso meio de comunicação é o meio humano para a transferência de dados radiais. Além disso é necessário escrever com clareza , ou seja, ser direto e objetivo , em seguida é necessário explicar a lógica e por fim exemplificar a nossa lógica.
Certo & Errado
Como já disse muitos tutoriais tem tendência a ensinar como escrever o código e isso é errado.
O que nós queremos é explicar a lógica, isso será o mais correto.
Exemplo:
Irei exemplificar o que é certo e errado com um código de condicionais e atribuição de valores.
- Código:
nova var_1 = 0 ;
nova var_2 = 25 ;
if ( var_1 == 0 )
{
var_2 = var_2 * var_2;
}
É recomendável usar comentários no código para explicar o que cada linha faz, mas o tutorial não deve ser um código com comentários.
peão Код:- Código:
nova var_1 = 0 ; //variável var_1 com valor 0
new var_2 = 25 ; //variável var_2 com valor 25
if ( var_1 == 0 ) //se var_1 for igual a 0 entгo:
{
var_2 = var_2 * var_2; //atribuir o valor de var_2 * var_2 a var_2 , isto seria var_2^2
}
Isto é um bom uso dos comentários, pois assim nгo teremos que fazer:
Agora criamos uma varбvel com valor 0 e outra com valor 25
peão Код:Agora criamos uma varбvel com valor 0 e outra com valor 25
- Código:
nova var_1 = 0 ;
nova var_2 = 25 ;
Depois criamos uma condição
peão Код:- Código:
se ( var_1 == 0 )
Desta forma o nosso tutorial tornara-se chato pois assim sу veremos cуdigo, a ideia seria explicar e depois exemplificar, ex:
Para fazer uma condiзгo utilizamos o if e abrimos parenteses, depois definimos a nossa condiзгo, ex:
peão Код:Para fazer uma condiзгo utilizamos o if e abrimos parenteses, depois definimos a nossa condiзгo, ex:
- Código:
nova var_1 = 0 ; //variável var_1 com valor 0
new var_2 = 25 ; //variável var_2 com valor 25
if ( var_1 == 0 ) //se var_1 for igual a 0 entгo:
{
var_2 = var_2 * var_2; //atribuir o valor de var_2 * var_2 a var_2 , isto seria var_2^2
}
Resumo: Neste código criamos duas variáveis com valores pré-definidos, em seguida utilizamos o if e definimos a condição var_1 == 0 na qual verifica se a variável var_1 é igual a 0, caso a condição seja verdade aplicamos uma operação matemática na qual atributos um valor à variável var_2, o operador matemático que utilizamos à o da multiplicação ( * ) e esta operação seria o mesmo que var_2 ^ 2.
Este é um bom exemplo de como as coisas devem ser explicadas, para que dessa forma os tutoriais garantam bem intuitivos e explicativos, além de limpos e legíveis.
Este é um bom exemplo de como as coisas devem ser explicadas, para que dessa forma os tutoriais garantam bem intuitivos e explicativos, além de limpos e legíveis.
Outras coisas
Por fim podemos dar cor ao texto, para que o mesmo não fique uniforme e seja variado, criando assim uma diferenciação no texto e não uma monotonia na leitura.
Creditos: Rebelox