[RebeloX]

Dicas para fazer um bom tutorial

Os tutoriais й uma das coisas mais importante numa comunidade de programaзгo, pois estes permitem a partilha de conhecimentos entre pessoas mais experientes e menos experientes, 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гo parei, no inicio nгo tinha uma grande estrutura entгo ao longo do tempo fui melhorando e acabei 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 que o nosso conhecimento й correto e nгo errado, claro que algumas vezes isso pode acontecer por isso que existem as tais criticas-construtivas, essas criticas servem para nуs aprendemos 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 й partilhar 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б comprovar a nossa teoria.

Saindo um pouco da filosofia e voltando ao assunto, existem algumas coisas fundamentais 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 cerebrais. 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 isto й 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.

pawn Код:

new var_1 = 0;
new var_2 = 25;

if(var_1 == 0)
{
    var_2 = var_2 * var_2;
}

Й recomendado utilizar 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.

pawn Код:

new 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

pawn Код:

new var_1 = 0;
new var_2 = 25;

Depois criamos uma condiзгo

pawn Код:

if(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:

pawn Код:

new 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 atribuнmos 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 fiquem 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.