Como escrever um bom HowTo

Howtos são sempre muito úteis. Não importa o assunto que é abordado.
Se você está tentando contribuir com um projeto Open Source ou se está atraindo tráfego para o seu blog, howtos podem deixar as coisas mais fáceis.

Escrevi esta lista de passos para servir de exemplo enquanto escrevo um howto, as pesquisas são baseadas nas definições de howto da Wikipedia e com as minhas próprias experiências.

1. Tente deixar pequeno

• Seja específico. Howtos devem ser escritos para guiar uma tarefa específica, não discuta outros tópicos, mesmo que eles estejam relacionados. Guarde para um outro tópico.
• Deixe detalhes irrelevantes para apêndices ou outros documentos de referências. Detalhes tendem a distrair os leitores.
• Divida em vários arquivos se for um post longo e para leitura online.

2. Deixe legível

• Seja informal, imagine o leitor na sua frente.
• Destaque informações importantes. Muitos leitores visualizam o documento procurando apenas um pedaço da informação.
• Sumarize e categorize. Isto não apenas ajudará o seu leitor a encontrar rapidamente o que ele estava procurando como também organizará as suas idéias enquanto estiver escrevendo.
• Use listas e seções. Isto ajuda-o a alcançar o próximo tópico. O howto inteiro pode ser uma lista se você estiver escrevendo um assunto simples como este.

3. Use recursos visuais

• Use imagens ou vídeos. Eles podem poupá-lo de muitas palavras, mas não abuse desses recursos porque há pessoas com conexões muito baixas. Contudo, howto de vídeo pode ser uma boa escolha para tarefas complexas.

4. Mantenha-o simples

• Talvez o ponto mais importante seja resumir todos os tópicos anteriores. Howtos são entendidos como algo que deixa as coisas mais claras.
• Use termos técnicos apenas quando for necessário, a não ser que seja para alcançar um público que entendem tais termos.
• Construa um glossário com os termos técnicos ou aponte-os a um wikipage que explique melhor.

Referência: How To Write a Good Howto