Escrevendo posts técnicos em blogs sobre projetos de programação

Dá para dizer que escrever código é mais fácil do que escrever sobre código. Basicamente, o código funciona ou não, enquanto a linguagem natural pode falhar ou dar certo de todas as maneiras possíveis. Mas se você é um programador experiente, já possui a maior parte das habilidades necessárias para ter sucesso nesse outro tipo de escrita, e outros desenvolvedores podem se beneficiar quando você compartilha suas ideias.

Escrever um post de blog é semelhante a escrever código:

• Você desenvolve uma ideia e traça um plano de como vai partir do zero até sua plena concretização.

• Você segue as regras sintáticas para evitar interpretações errôneas.

• Você se esforça para ser suficientemente detalhado a fim de ser compreendido, ao mesmo tempo em que simplifica sempre que possível.

Quando você estiver escrevendo sobre código, há técnicas adicionais que você pode usar. Mas é importante também manter o foco no que o leitor espera do seu post. Uma vantagem que os posts de blogs técnicos têm em relação a outros tipos de texto é que o que o leitor quer costuma ser bastante óbvio.

Redação Técnica Eficaz

O problema é que a redação técnica é enfadonha. Diferentes pessoas têm diversas estratégias para amenizar isso, mas nem mesmo truques engenhosos conseguem mudar esse fato fundamental. Ler explicações abstratas sobre algoritmos e sintaxe é uma tarefa difícil. O cérebro –especialmente a memória– funciona por meio de associações, e as informações técnicas oferecem poucos pontos de apoio para essas associações.

Isso não se aplica apenas à redação técnica. Se você já teve dificuldade para ficar acordado durante uma aula ou palestra de meia hora, mas não tem problema em se concentrar em um filme de duas horas, você já sabe disso. O tédio tem menos a ver com as pessoas que recebem a informação do que com a forma como ela é apresentada.

Por que as pessoas leem posts técnicos em blogs? Na maioria das vezes, elas querem saber como realizar uma tarefa ou se aprofundar em um tema específico. Seu desafio é atender a essa necessidade antes que a atenção delas se esgote.

A única coisa que quase sempre melhora a redação técnica é reduzi-la. Isso vale tanto para o tamanho da postagem quanto para o comprimento das frases. Vale até mesmo para os exemplos de código que você usa. Assimilar informações técnicas já é um desafio grande o suficiente para o nosso cérebro. Você pode ajudar as pessoas a entenderem o assunto, assumindo a tarefa de priorizar as informações para elas e removendo tudo o que não for essencial.

Existem várias abordagens diferentes que você pode usar para simplificar o texto que ficou. Algumas ferramentas eficazes são:

• Humor

• Antropomorfização de conceitos ou código

• Imagens (GIFs, não gráficos circulares)

• Exemplos interativos

• Código

• Listas com marcadores

Algumas dessas técnicas afetam a própria escrita, enquanto outras proporcionam uma pausa nela. Mas todas elas utilizam áreas do cérebro diferentes daquela que se encarrega de memorizar fórmulas e algoritmos. As memórias são formadas por conexões entre partes do cérebro, e lembrar-se do que você está lendo à medida que avança é fundamental para evitar o esgotamento mental por tempo suficiente para compreender o panorama geral.

Se você ainda não tem muita experiência com redação técnica, ou se ainda não produziu muitos textos com os quais se sinta satisfeito, talvez valha a pena experimentar outras maneiras de tornar a redação mais leve. A voz autêntica do autor é tão importante em um post de blog sobre código quanto em qualquer outro lugar. Sua voz ganha mais destaque quando você tem uma estratégia bem planejada que soe natural.

Termos técnicos

É claro que tudo bem falar sobre fazer piadas e incluir GIFs para dar um toque especial ao seu texto, mas, em algum momento, você vai ter que mergulhar nas águas turvas das siglas e da notação húngara.

A primeira maneira de lidar com a terminologia técnica é dar um passo atrás e certificar-se de que definiu o escopo do seu post corretamente. Um post de blog em que você precisa dedicar vários parágrafos para explicar cada termo técnico provavelmente não deveria ser o mesmo em que você usa vários termos técnicos em uma única frase. Se você perceber que está misturando muitos termos técnicos e achar que ninguém conhece todos eles, pode incluir um link para a definição padrão do termo, em vez de correr o risco de explicar demais. Você também pode dividir sua postagem em duas partes, com uma introdução opcional que aborde todos os conceitos básicos que algumas pessoas talvez queiram pular.

Para tornar seu texto menos enfadonho, incorpore termos técnicos ao fluxo narrativo da sua postagem. Assim, em vez de:

"getData é o nome da função que obtém os dados. Seu valor de retorno é output. Ela pode não retornar nada ou retornar um objeto. Ela recebe dois argumentos. source é o primeiro argumento, e filter é o segundo, que é opcional."

Você pode integrar termos técnicos à linguagem natural da seguinte maneira:

"Ao passar um dado source como getData como seu primeiro argumento, podemos obter um output objeto contendo nossos dados. Opcionalmente, podemos adicionar um filter para filtrar os dados retornados. Se não houver correspondências, getData ela simplesmente retornará null."

Pode ser tentador tratar os termos técnicos com uma certa formalidade, mas acho que isso torna o texto muito mais difícil de entender. A maneira como você falaria com alguém com quem estivesse fazendo programação em pares sobre o código em que estão trabalhando juntos ficará imediatamente mais clara.

O papel da formatação

Alternar entre nomes de narrativa e de variáveis sem deixar claro o que você está fazendo é possível graças às <code> tags no HTML final da sua postagem. Elas fornecem uma indicação visual de que você está se referindo a um elemento específico da solução técnica e também podem ser reconhecidas por tecnologias assistivas. Qualquer outra formatação de termos técnicos, como colocar em negrito o nome de uma determinada tecnologia ou ferramenta, fica a seu critério ou de acordo com o guia de estilo da sua organização.

A forma como você formata os blocos de código também é importante. No mínimo, é útil ter destaque de sintaxe. Isso não só torna o código mais fácil de entender visualmente, como também confere um toque visual interessante à sua postagem. O código nos blocos deve ser organizado para a sua postagem. Se os comentários no seu código explicarem o mesmo que a postagem do seu blog, você pode removê-los para apresentar menos código. Você também pode remover qualquer recuo herdado do código, para que não seja necessário rolar a tela horizontalmente para lê-lo.

Dividir sua postagem em subseções é útil para organizar as informações e, dependendo da plataforma de blog que você estiver usando, pode oferecer atalhos de navegação dentro da própria postagem. Você também pode usar notas à margem e listas com marcadores para organizar a postagem. Só não exagere na formatação. A maioria das postagens de blog provavelmente ainda deve ser composta principalmente por texto, mesmo que sejam sobre código.

Incluir links para outros recursos requer um pouco de estratégia. Se você encontrou algo útil e inserir um link para esse conteúdo se encaixa naturalmente no fluxo do seu texto, é bom ter essas informações adicionais no contexto. Mas você não deve adicionar tantos links no texto a ponto de causar distração. Se tiver muitos itens para vincular, você sempre pode colocar uma lista no início ou no final da postagem. Isso também tem uma vantagem: não incentiva as pessoas a interromperem a leitura e irem para outro lugar no meio do tutorial.

Uso de imagens

O uso de imagens é bastante comum em matérias jornalísticas e outros tipos de conteúdo que podem passar por um processo de produção mais demorado do que uma postagem de blog. Também é comum incluir pelo menos uma imagem principal em artigos técnicos. Já abordamos a importância disso.

As postagens em blogs técnicos também podem usar imagens no corpo do texto. Elas podem servir para dar um toque visual, como GIFs para dar um intervalo no texto, ou podem ter uma função explicativa. As únicas considerações em relação às imagens decorativas dizem respeito a questões legais e de acessibilidade. Desde que haja permissão para usar a imagem e que as legendas sejam bem elaboradas, não deve haver problema.

Alguns conceitos técnicos se beneficiam de uma demonstração visual. Você pode capturar a tela das etapas de um processo de configuração ou transformar o processo em um GIF. Mostrar estruturas de diretórios, exemplos de resultados ou uma interface de usuário que você não esteja programando na postagem também pode ser útil. No entanto, é importante não depender totalmente de imagens para essas coisas. Você ainda deve explicar o que está na imagem ou fornecer informações suficientes para que as pessoas possam reproduzir o mesmo resultado localmente.

Explicando o código

Se você pretende escrever um post de blog sobre um trecho de código, deve se preparar para explicar esse código. Indicar um repositório aos leitores, comentar algumas linhas e mencionar seu nome de usuário no Twitter provavelmente não resultará em um post de blog muito útil.

Se o código da sua postagem no blog for escrito especificamente para esse fim (e não fizer parte de um projeto maior), é muito útil acompanhar as etapas que você segue para criá-lo à medida que vai programando. Isso lhe dará um esboço pronto para a postagem. Você pode até mesmo anotar literalmente essas etapas na própria postagem do blog e, assim que o código estiver pronto, voilà, seu esboço já está pronto. Se o código for apenas uma parte de algo maior, identifique quais partes são essenciais para o tema da sua postagem e organize-as de forma que as primeiras partes que você abordar sejam as que servem de base para as seguintes.

Essas são sugestões genéricas, é claro. Se você estiver analisando o código de outra pessoa ou apenas explicando algo realmente complexo, começar pelo produto final e adotar uma abordagem do tipo “como eles fizeram isso?” pode ser uma ótima ideia.

Um truque que acho que funciona bem é escrever a narrativa em torno do seu código como se os exemplos de código não estivessem lá. Outra maneira de pensar nisso é como se você estivesse fazendo uma entrevista de programação e precisasse expressar as partes importantes da solução, sem especificar os detalhes de implementação. As pessoas provavelmente estão procurando em um post de blog algo que não conseguem obter apenas olhando para o repositório do GitHub; portanto, um post de blog deve ir além de simplesmente dizer: “Agora vamos adicionar a getData função:”. Existe um equilíbrio ideal entre isso e repetir o bloco de código inteiro em linguagem natural.

A maneira como você divide seu código pode ajudar a encontrar o equilíbrio certo entre explicação e autodocumentação. Se você conseguir dividir seu código em blocos com cerca de dez linhas importantes (partes que não sejam código padrão ou parênteses de fechamento), poderá escrever um parágrafo de 2 a 3 frases explicando cada um deles e manter um bom ritmo. Mas nem sempre é possível fazer isso. Algumas funções são enormes.

Se o código que você precisa discutir for muito longo, considere dividi-lo artificialmente. Eu prefiro fazer isso deixando comentários de preenchimento como //INSTANTIATE VARIABLES e //FETCH VALUES, para não precisar alterar o funcionamento do próprio código e, assim, evitar a possibilidade de introduzir um bug no último minuto. No entanto, dividir um código longo em módulos ou funções separadas também funciona. Adicionar abstrações torna seu código muito mais fácil de discutir, e o mesmo benefício de reutilização que você obtém no próprio código é algo que suas postagens no blog também podem aproveitar. Se você escrever sobre um assunto semelhante novamente, poderá reutilizar essas partes e talvez até mesmo suas explicações.

Conclusão

No final da sua postagem, é útil confirmar qual é o resultado esperado. Se o leitor estiver programando passo a passo e estiver encontrando erros, ele provavelmente já suspeita que houve algum mal-entendido. Mas nem sempre é assim. Você pode concluir dizendo: “Agora você já tem o código do seu aplicativo pronto. Basta configurar suas credenciais de API seguindo este tutorial e você poderá executar o aplicativo.”

Se você chegar ao final do seu post e não tiver muito mais a dizer, isso é um bom sinal de que definiu o escopo do post corretamente. Se estiver enfiando muitas ressalvas em parágrafos extras, considere voltar e corrigir no código ou no post aquilo que está incomodando você.

A etapa final na redação de um post técnico de blog é a mesma de um post não técnico: a edição. No caso de um post técnico, é importante verificar manualmente todas as sugestões fornecidas por uma ferramenta de revisão automática. Se você precisar fazer alterações nos blocos de código, certifique-se de que o código ainda funcione depois disso.

Se você tiver interesse em escrever um artigo técnico para um blog sobre seu trabalho com as APIs da Vonage, estamos aceitando inscrições para o nosso programa “Developer Spotlight” .