Skip to content

Instantly share code, notes, and snippets.

@khaosdoctor
Created May 14, 2020 15:58
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save khaosdoctor/d65d489374f22af62d853b1984baed6f to your computer and use it in GitHub Desktop.
Save khaosdoctor/d65d489374f22af62d853b1984baed6f to your computer and use it in GitHub Desktop.

Por que você deveria começar a escrever artigos técnicos {ignore=true}

Recentemente estive passando pelos tópicos no DEV Community e encontrei um excelente artigo sobre algumas dicas para pessoas que queiram começar a escrever artigos técnicos. Então resolvi escrever um artigo com a minha própria opinião sobre o assunto e também referenciar algumas partes deste conteúdo sensacional.

Algumas das dicas e referências a seguir serão copiadas deste artigo somente para fins práticos, para evitar que o leitor tenha que buscar o conteúdo no artigo original. Porém, as opiniões sobre ele são próprias.

Sumário {ignore=true}

Por que escrever

Todas as pessoas, sendo programadoras ou não, deveriam escrever sobre o que fazem e sobre o que estão aprendendo, ou então escrever somente sobre a vida que estão levando.

Um ponto interessante que é colocado no artigo é algo que não pensamos muito. Sempre que lemos um conteúdo técnico na Internet, associamos o criador daquele conteúdo como sendo uma autoridade ou pelo menos tendo certa autoridade no assunto, e isso é algo extremamente positivo para a sua carreira e também para você como pessoa.

Ser associado com experts no assunto é sempre uma boa prática. Quando as pessoas leem seu artigo na Internet, elas te reconhecem como um profissional e confiam mais no que você diz.

(Extraído da referência)

E este é, entre outros, um dos pontos por que você, como pessoa desenvolvedora, deveria começar a escrever conteúdo técnico, a consolidação do seu status como profissional do desenvolvimento pode te ajudar em sua carreira futura e também influencia na maneira como você lida com as situações. Alguém que está sempre escrevendo ganha habilidades importantes para o mercado de trabalho:

  • Aumenta a sua desenvoltura falada e escrita: portanto, melhora a sua forma de lidar com clientes e outros colegas, além disso, te ajuda a criar e expor argumentos de forma mais clara e concisa.
  • Faz com que você tenha uma nova forma de pensar: O processo de criação de artigos é algo bastante elaborado, conforme vamos falar mais para frente, ele exige que você tenha uma organização e uma forma de construção concreta, você não vai conseguir escrever algo se simplesmente jogar suas ideias ao ar. Pensar na forma de escrita é uma ótima maneira de começar a ver o mundo de forma diferente
  • Te prepara para feedbacks: Ao nos expormos na Internet estamos sujeitos todo tipo de resposta, boa ou ruim, e é importante sabermos lidar com ambas. Isso faz com que desenvolvamos a habilidade de saber responder críticas de forma ponderada e lidar com elogios de forma humilde.

Mas falamos muito do que escrever desenvolve como habilidade, mas, além disso, por que devemos começar a escrever?

Consolida seu aprendizado

Você provavelmente já ouviu a frase: "Só aprende de verdade quem ensina a outra pessoa", ou alguma de suas variações, certo?

Isto é real. Ensinar outra pessoa força você a buscar correlações e consolidar o seu conhecimento. Uma forma bastante simples de fazer isso é escrevendo sobre ele.

Escrever faz com que você precise pensar na forma mais simples e fácil de fazer a pessoa que está lendo entender o conteúdo que você quer passar, isso ajuda a consolidar sua experiência e seu conhecimento de forma simples e rápida.

Ou então, se você é como eu, sua motivação para escrever artigos pode vir simplesmente da vontade de compartilhar conhecimento com outras pessoas e querer observar e analisar pontos de vista e opiniões diferentes das suas.

Aparecer para o mundo

Como profissional, é importante que outras pessoas saibam o que você está fazendo e como você se destaca nisso, você quer que as pessoas te conheçam pelo que? Se você tem um sonho de começar a trabalhar em uma empresa mas não sabe como alcançar este sonho, uma das opções é justamente aparecer mais, afinal, todas as empresas são compostas de pessoas e estas precisam saber que você existe.

Além de uma vantagem profissional, escrever também te coloca, invariavelmente, em um patamar de pessoas que, aos olhos de outras, se tornam referências sobre o que estão falando, pois muitos vão buscar seu conteúdo para completar trabalhos de escola ou até mesmo criar projetos pessoais.

Eu, até hoje, me lembro que, em 2010, quando estava começando a aprender a programar e, mais do que frequentemente, caia no site do grande José Carlos Macoratti – na época, eu programava em .NET – e, até hoje, ele é uma das minhas maiores referências, mesmo não tendo tocado em um código C# há quase dez anos. Lembre-se da icônica frase de Isaac Newton:

Se enxerguei mais longe foi porque me apoiei sobre os ombros de gigantes

(Isaac Newton)

Você pode ser um dos gigantes onde outros gigantes se apoiaram para desenvolver suas criações, você provavelmente nunca vai saber disso, mas outras pessoas – talvez aquela pessoa gerente de RH na empresa onde você tanto quer trabalhar – vão!

Um arquivo para o futuro

Por último, mas não menos importante, escrever cria um repositório de conhecimento que pode ser a diferença entre o sucesso ou o fracasso de um projeto. Você não precisa escrever com o objetivo de se tornar famoso, mas sim para registrar o seu conhecimento para si, criando um arquivo de informações úteis que você pode buscar quando precisar.

Um exemplo pessoal – que já me salvou mais de uma vez – é o meu repositório de notas, um local simples que, há mais de três anos, escrevo todos os meus aprendizados de praticamente todos os cursos que já fiz em minha vida. Lá estão repositórios de exemplo, dicas e truques, ideias e até planejamentos inteiros de palestras.

Escrever sobre algo publicamente – ou mesmo de forma privada – te faz registrar e ter uma documentação mental por escrito daquele momento, pense como um snapshot do seu cérebro em uma determinada época.

Os problemas de devs na escrita

Nós somos devs, não somos jornalistas ou repórteres, muito menos escritores profissionais. Tudo conspira para que o dev jamais escreva algo. Dentre os maiores problemas para devs na escrita temos:

  • Timidez: Devs são pessoas naturalmente introvertidas – muitas vezes é a razão pela qual escolhemos a profissão, máquinas são muito mais simples de lidar do que pessoas – e isso impacta duramente na expressão para um mundo todo através da Internet, mas isso pode ser superado, um exemplo muito legal é o artigo da Mariane Santana, que nunca tinha escrito antes e agora está na lista dos 7 artigos mais lidos do DEV Community 🤘
  • Planejamento: Devs geralmente tem ansiedade elevada, mas não adianta querermos escrever tudo de uma vez, precisamos ter um planejamento
    • Agende os seus artigos: Conforme eu falei em minha série sobre organização pessoal, tudo precisa se tornar uma tarefa planejada, e com artigos não seria diferente, planeje as datas com antecedência
    • Saiba seu tema: Saiba com antecedência sobre o quê você quer escrever
    • Planeje seu conteúdo: Escreva em uma em qualquer lugar, um outline do seu artigo, com os principais títulos e tópicos
  • Falta de prática: Infelizmente aqui não podemos mudar muita coisa a não ser dizer a prática leva a perfeição... Você só vai conseguir escrever melhor se praticar escrevendo cada vez mais. A leitura também ajuda muito a aumentar o seu vocabulário de escrita e melhorar a forma como você escreve
  • Medo de ser criticado: Como já mencionei, quando nos expomos na Internet, estamos sujeitos a todo o tipo de crítica, então muitas pessoas não escrevem pelo receio de serem duramente criticadas. Neste caso, não temos muito o que fazer, apenas tenha pleno conhecimento do que você está escrevendo e se sinta pronto(a) para responder perguntas – não interagir também é uma opção.

Como escrever um artigo técnico

Sobre o que falar

Você pode escrever literalmente sobre qualquer coisa. Que tal sobre a sua experiência usando uma ferramenta? Ou então o seu processo de aprendizado? Talvez sobre como seu estudo de música influenciou a sua vida como dev. Enfim, você escolhe!

Ninguém vai esperar que você escreva sobre algo que está fora da sua área de atuação, e muito menos que você seja a referência máxima em algo que você está aprendendo (desde que você deixe claro que esteja aprendendo), você pode ficar desconfortável com isso, mas por outro lado, ter uma perspectiva sobre como VOCÊ faz as coisas e como é a SUA rotina pode ajudar outras pessoas a entender como serem melhores. Pontos de vista... sempre...

Outras ideias de escrita:

  • Experiências próprias sobre algum assunto
  • Novidades sobre suas tecnologias favoritas
  • Histórias de vida, suas ou de outros
  • Aprendizados, fracassos, sucessos e lições que você teve em sua jornada

Pesquisa e opinião, varie seu tópico

Um passo muito importante da escrita técnica é a busca. Você provavelmente não vai ser o primeiro a escrever sobre alguma coisa. Mas pesquise muito bem antes de começar a escrita do seu tema.

  • Veja se existem outros artigos com o mesmo tema. Não há problema em escrever artigos sobre a mesma coisa – da mesma forma como estou fazendo aqui – apenas se certifique que não é um plágio e deixe sempre referências para o conteúdo original. Veja algumas opções:
    • Conteúdo da sua experiência pessoal sobre o tema
    • Uma opinião diferente
    • Um adendo ao tema (como este artigo)
    • Tradução para outra língua
  • Procure o máximo possível de pontos de vista distintos sobre o mesmo assunto, quanto mais opiniões você incorporar, mais rico seu artigo ficará

Dando um título

O título do seu artigo é o que fará com que as pessoas se interessem em lê-lo. Então ele precisa ser bem pensado. O título deve ser claro, conciso e deve indicar o propósito do artigo. Vou usar alguns exemplos do artigo de referência traduzidos:

  1. Roundup #58: Orleans 3.0, Snitch, Qual é o seu problema? Próximos 5 anos de ASP.NET Core
  2. A Linguagem de Programação para Todas Comandar
  3. Sofrendo de Débito Técnico?

Veja por que estes exemplos são ruins:

  1. Muitas keywords, muita coisa acontecendo, o título é muito longo e parece que fala sobre absolutamente tudo
  2. Muito "esotérico", claramente parece um clickbait, mas não dá muito a entender sobre o que o material fala (isto também vale para o 3)
  3. Uma pergunta ao leitor como um título não é um bom título. Ela gera dúvida e isso gera expectativa de resposta, se a resposta que você der não satisfazer o leitor, então você acabou de manchar a sua reputação para aquela pessoa específica.

Agora alguns bons exemplos:

  1. Carreira em Programação e Música: O que aprendi com isso tudo?
  2. Desenvolvendo uma Aplicação CRUD Node.js com PostgreSQL
  3. Tutorial: Data pipeline usado MongoDB e Kafka Connect no Kubernetes

Todos os artigos que listei possuem nomes concisos, simples de se ler e que dizem exatamente sobre o que vão falar. Da mesma forma, eles não são longos e as palavras-chave estão claras em cada um deles.

Veja que o artigo da Ana sobre música contém uma pergunta, mas ela não é direcionada ao leitor, e sim uma pergunta retórica que remete a ela mesma, explicando do que o artigo se trata.

Estrutura

Todo o artigo segue uma linha de raciocínio, isso é algo que aprendemos na escola em nossas primeiras redações, todo o texto possui:

  • Título
  • Introdução
  • Desenvolvimento (Aqui é onde colocamos o código, imagens, exemplos)
  • Conclusão
  • Referências

Com artigos técnicos não é diferente, a única coisa que será um pouco diferente é a parte das Referências que é geralmente utilizada como uma seção onde você pode ligar um artigo ao resto do seu trabalho.

Tempo

Um artigo da Data Lab mostrou que o tempo ideal de um artigo é de sete a dez minutos. Isso não é uma regra, mas ajuda a te guiar para o tempo que seu conteúdo deve ter. Eu, particularmente, uso uma extensão para o VSCode que me mostra estas informações.

Porém não há problema em passar deste tempo se você está escrevendo um artigo mais detalhado ou um tutorial, afinal, é o seu conteúdo. Apenas leve em consideração a capacidade de quebrá-lo em mais de um, formando uma série, como faço com muitos artigos meus

Conteúdo

As pessoas esperam ler o conteúdo que você está dizendo que vai passar. Evite usar palavras muito complexas, ou escrever como se fosse um artigo científico – a não ser, claro, que este seja seu intuito.

Inclua imagens sempre que possível, gists e use o Carbon ou o CodePen para incluir códigos.

Algumas outras dicas de conteúdo:

  • Evite ser completamente informal, mas evite também ser muito formal
  • Veja aplicativos como o Grammarly (se estiver escrevendo em inglês), confie em extensões de analise de texto
  • Sempre revise seu texto antes de publicar
  • Veja se outra pessoa pode ler o texto para que ele possa ser revisado
  • Expanda acrônimos quando forem usados pela primeira vez no artigo, por exemplo: "O uso do AKS (Azure Kubernetes Service) ..."
  • Prefira utilizar a primeira pessoa do plural quando escrever artigos – a não ser que seja um artigo de opinião – pois "nós" cria um senso de coletividade com a pessoa que lê
  • Não faça parágrafos muito longos
  • Sempre que prover dados (números, etc), cite a data e fonte de onde eles vieram

Tags

Keywords, ou palavras-chave, são importantes porque será através delas que mecanismos de busca vão indexar seu texto. Para procurar por quais tags você pode utilizar, veja alguns exemplos diretos do artigo que referenciei:

  • moz.com
  • app.neilpatel.com
  • trends.google.com
  • keywordtool.io
  • wordtracker.com/scout

Use pelo menos 5 tags para indicar o que você está escrevendo, em nível decrescente de mais genérico para mais específico, por exemplo: open-source, back-end, javascript, node.js, cli

Divulgue

Não tenha medo de divulgar o seu trabalho da maior forma possível, utilize ferramentas como o MLabs, Hootsuite e outras para fazer a gestão de suas redes sociais mais utilizadas, agende seus posts. Faça uso de grupos em redes sociais que sejam especializados no que você está escrevendo, seu público está por lá.

Dica: Mantenha postagens recorrentes sobre seu artigo, mas evite duplicar o texto, muitos algorítmos de redes sociais identificam posts duplicados na mesma conta como spam.

Conclusão

Tentei escrever de forma mais simples e concisa tudo o que aprendi escrevendo artigos técnicos nestes últimos anos. Espero que, com estas dicas, você também se inspire a escrever mais e compartilhar o seu conteúdo.

Se você quer começar a escrever mas não sabe se seu artigo está legal e quer uma segunda olhada ou então você já escreve e quer compartilhar, me manda seu conteúdo através das minhas redes sociais, eu adoraria dar uma olhada!

Você pode encontrar todas elas no meu site: https://lsantos.dev!

Até mais!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment