Writing a Technical Blog

The post says technical blog ideas often come from moments when you solve a problem, explain something to a coworker, finish a big feature, research something, build something for fun, or take detailed notes on something you just figured out. From there, it suggests choosing whether the post is a guide or a reference.

For a guide, it recommends stating prerequisites, identifying the reader’s skill level, starting from a blank slate, and giving context around code, including file names when the code spans multiple files. For a reference, it suggests outlining headings first, then adding more headings as the explanation grows, because reference posts can become dense. It also says to leave the draft for a day or two, read it out loud, ask someone else for feedback, and revise for repetition and clearer connections between concepts.

Fichamento

#

• Ideias para blog técnico podem surgir ao resolver um problema, ensinar algo a um colega, terminar uma feature grande, pesquisar um tema, construir algo por diversão ou registrar com detalhe o que acabou de entender.
• Depois de escolher a ideia, o texto propõe decidir entre um guia e uma referência.
• Um guia leva o leitor passo a passo e pede que o autor defina o nível do público, as noções prévias e os pré-requisitos logo no início.
• Em um guia, o ponto de partida deve ser o ponto zero, e o código precisa vir acompanhado de contexto, inclusive nomes de arquivos quando houver vários arquivos.
• Um texto de referência explica um conceito em vez de mostrar passos, e começa com um esboço de headings.
• Conforme a explicação avança, o autor pode perceber que precisa acrescentar headings ou transformar a ideia em um novo blog.
• Como textos de referência ficam densos com facilidade, headings e memes ajudam a quebrar o texto.
• Na edição, o autor recomenda deixar o texto parado por um ou dois dias, ler tudo em voz alta e pedir feedback de outra pessoa.
• Na revisão, o texto pode ser afinado para cortar repetições, reescrever frases e deixar mais explícitas as relações entre os conceitos.
• O encerramento diz que explicar algo para outra pessoa ajuda a entender melhor o assunto e que blogs técnicos ajudam o autor e os leitores a aprender ao mesmo tempo.