Compartilhando seu conhecimento com o mundo! Como escrever artigos

Compartilhar conhecimento escrito é uma ótima forma de dominar um assunto específico, além de ser uma excelente maneira de melhorar a organização das ideias, comunicação e obviamente se autopromover na comunidade. Essa produção de artigos tanto técnicos quanto sociais são muito importantes tanto para quem escreve quanto para quem está lendo, lembre-se sempre: Você sabe mais hoje do que quem começou ontem. Pensando nisso vamos discutir um pouco mais sobre como organizar as próprias ideias na produção de um artigo técnico para a plataforma dev.to!

Table of contents

• Método de Feynman e por que produzir conteúdo
• Coletando ideias e se motivando para escrever
• Entendendo a plataforma e achando a propria linguagem
• Aprendendo markdown e dicas gerais para uma boa formatação
• A estrutura básica de um artigo técnico
• Como revisar e melhorar a escrita
• Conclusão e agradecimentos

Método de Feynman e por que produzir conteúdo

Primeiramente precisamos discutir o porquê devemos compartilhar conteúdo, seja em formato textual (o foco desse artigo) ou em qualquer outro formato. Para iniciar essa discussão é importante entender o que é o método de Feynman e como ele pode nos ajudar a aprender 10 vezes mais com confiança e domínio do assunto.

O método de Feynman foi criado por um físico muito importante chamado Richard Feynman visando desenvolver uma abordagem nova ao aprendizado, essa nova proposta assume uma verdade central: "Se você não consegue explicar algo de maneira clara e simples, então você ainda não entendeu completamente".

Essa frase nos ajuda muito a pensar em como nosso aprendizado deve ser estruturado, pois a partir do momento que começamos a pensar em ensinar o que estamos estudando focamos muito mais em dominar as bases essenciais do assunto e se preparar para dúvidas que te forçam a olhar o problema, por outro lado, completamente diferente.

Ao se preparar para situações como essas, o resultado claro é uma excelente confiança e domínio sobre o assunto em questão que estava sendo estudado.

Eu particularmente amo esse método, o único problema dele é que quando saímos do ambiente acadêmico fica muito difícil de achar pessoas que se interessam pelo mesmo assunto que você esta estudando no momento, seja por não ter pessoas de TI no ciclo de amizade ou simplesmente por ter interesse em assuntos específicos.

Para esse problema temos uma solução muito incrível chamada "Learning in public"! Essa prática consiste em compartilhar seu aprendizado online em comunidades de tecnologia, seja produzindo vídeos, fazendo live streams ou no objetivo desse artigo: escrevendo!

Plataformas como o dev.to (que você usando para ler agora :D) visam tornar a ideia de "Learning in public" cada vez mais simples e próxima de quem está consumindo, pois agora é possível produzir artigos que vão chegar em pessoas com os mesmos interesses que os nossos que podem: aprender, tirar dúvidas ou mesmo sugerir mudanças e corrigir pensamentos. Incrível né?

Coletando ideias e se motivando para escrever

O processo de inspiração é provavelmente uma das fases mais chatinhas antes de produzir um artigo online, muitas vezes ficamos presos em um loop infinito de técnicas mirabolantes para ter ideias incríveis quando, na verdade, a solução acaba sendo muito simples: aceite suas ideias e consuma o máximo de conteúdos possível.

A forma mais prática de encontrar ideias e de construir sua própria linguagem é ler o que as outras pessoas já produzem sobre os temas que lhe interessam, quer se trate de uma linguagem de programação, de um tema específico em TI, etc; esse consumo de conteúdo vem de diversas fontes diferentes como artigos técnicos, vídeos no YouTube, tweets da bolha Tech, discussões no Github e muitos outros locais possíveis.

Bom, sei que falando assim parece simplificar algo que não é tão simples assim e eu concordo com você! Não é só ler ou assistir tudo o que existe na internet que vai nos tornar capazes de produzir os mesmos conteúdos, a habilidade mais importante que vai destacar essas pessoas é organizar as ideias que chegam no cérebro.

Mantendo um segundo cérebro

Nosso cérebro é uma excelente maquina de absorção de informação, praticamente uma esponja que guarda todas as informações ao nosso redor. O grande problema dessa maquina é que ela se tornou péssima em organização com o tempo, isso aconteceu principalmente para poupar energia já que não precisamos lembrar de tudo o tempo todo, mas sabendo disso o que podemos fazer para guardar as informações que queremos de forma organizada? Well well well jovem gafanhoto, precisamos parar de confiar no nosso cérebro é claro!

Manter um segundo cérebro é uma prática muito famosa entre escritores e pesquisadores, consiste em um local físico ou virtual onde você copia pequenos pedaços de conteúdo que consumiu junto de uma observação utilizando suas próprias palavras sobre o assunto. Esse amontoado de anotações vai compor o seu segundo cérebro e vai te empoderar com a habilidade de achar qualquer conteúdo rapidamente e referenciar seus autores sem nunca esquecer nada!

Para resumir a história, consuma o máximo de conteúdo possível, armazene-o em um segundo cérebro que pode ser armazenado e pesquisado e finalmente se desafie a escrever! Seja sobre um assunto que quer aprender, sobre algo específico que aprendeu recentemente ou até mesmo algo que domina há muitos anos.

Entendendo a plataforma e achando a propria linguagem

Entender a plataforma e o público que vamos atingir escrevendo nossos conteúdos é muito importante para podermos filtrar como vamos estruturar os artigos de forma geral certo? Na minha opinião, o dev.to é uma plataforma bem informal que valoriza muito conteúdos no formato de tutoriais com um estilo conversacional e direto ao ponto, com essa informação podemos deduzir algumas formas de estruturar nossos artigos para que possamos ilustrar nossa ideia em um modelo conhecido pelos leitores.

Isso significa que tudo o que você vai produzir são tutoriais diretos e informais? De forma alguma! Só significa que você pode moldar o seu conteúdo para conter essa linguagem mais informal, conversacional e direta mesmo que o tema tratado seja super complexo, isso inclusive vira um desafio muito interessante de simplificar o complexo.

A habilidade de simplificar o complexo vai te acompanhar para o resto da sua vida profissional, é importantíssimo a criação de analogias e exemplos para que facilite o entendimento e a identificação com os problemas apresentados e as soluções propostas.

Aprendendo markdown e dicas gerais para uma boa formatação

A forma para produzirmos nossos artigos no dev.to é utilizando uma linguagem de marcação (exatamente, igual o HTML) chamada Markdown, apesar dela ser super simples é importante termos um domínio bem solido do que é possível fazer quando falamos sobre organizar e deixar nosso texto bonitinho, semelhante como vamos produzir uma estrutura complexa no Microsoft Word devemos ser capazes de produzir o mesmo com código Markdown.

É sempre importante ressaltar a importância de um material educacional bem estruturado (afinal você está lendo esse artigo justamente para isso certo?) e quando o assunto é excelência e qualidade não consigo recomendar o suficiente o projeto 4noobs que junta em um único repositório diversos cursos grátis e no formato de texto sobre diversos assuntos em TI, para o tema desse artigo recomendo o uso do markdown4noobs no aprendizado da linguagem de marcação Markdown.

O básico sobre manipulação de texto e blocos de código

Markdown nos permite marcar partes do nosso texto com estruturas super básicas e necessárias como negrito, itálico, highlight, níveis de título, etc. Abaixo vamos ver rapidamente como realizar cada uma das ações com a sintaxe correta.

# Primeiro titulo equivalente a um h1
## Segundo titulo equivalente a um h2
### Terceiro titulo equivalente a um h3
#### Quarto titulo equivalente a um h4

`Texto em highlight`
**Texto em negrito**
*Texto em itálico*

Esses artifícios da linguagem markdown nos permitem controlar a narrativa a nosso favor e deixar a leitura mais simples de seguir, utilizando bold no meio do texto para chamar a atenção, deixar explicito um termo técnico usando highlight ou até mesmo utilizando imagens ilustrativas que introduzem o ponto do parágrafo enquanto mantém o clima geral do texto muito mais gostoso de ler.

Outra coisa importante de se mencionar é o bloco especifico que usei acima, ele é extremamente útil quando vamos escrever artigos técnicos, tanto, pois ele permite um destaque maior a um bloco de texto quanto ele permite habilitar syntax highlighting caso esteja escrevendo um bloco de código, ele é utilizado da seguinte maneira:

Disclaimer: Como markdown não permite um bloco dentro de um bloco optei por mostrar com um screenshot:

Após os símbolos de backtick, podemos incluir o nome da linguagem (no meu caso ruby) para que o dev.to possa habilitar o syntax highlighting especifico para essa linguagem de programação.

Tabela de conteúdo

Caso o seu artigo esteja ultrapassando a margem das duas mil palavras ou esteja com pelo menos 4 títulos principais, eu recomendo fortemente que deixe definido um Table of contents, ou Tabela de conteúdo. Essa tabela de conteúdo serve para guiar a leitura durante os pontos principais que serão lidados durante o artigo, para a criação de um existem uns macetes que vou demonstrar abaixo:

Na plataforma dev.to, use listas não ordenadas ao invés de listas numeradas

Listas em Markdown são bem simples de serem usadas e elas possuem dois tipos principais: não ordenadas e numeradas.

- Uma lista
- Não
- Ordenada

1. Uma lista
2. Numerada
3. Aqui

O problema de usar as listas numeradas no dev.to é que elas ficam desalinhadas como podemos ver no exemplo abaixo, portanto não recomendo o uso delas de maneira geral, sempre tento utilizar as listas não ordenadas e se for necessário aplicar alguma ordem utilizar um número após o símbolo da lista não ordenada manualmente.

Como organizar os links para um título

Assumindo que você já descobriu como estruturar um link no Markdown (já que você leu o markdown4noobs né?) vamos aprender os macetes simples para indicar um link em um título e como estruturar nossa tabela de conteúdo.

Uma tabela de conteúdo de exemplo pode ser vista abaixo:

## Table of contents

- [What is metaprogramming anyway?](#what-is-metaprogramming-anyway)
- [In ruby everything is an object, what does that mean?](#in-ruby-everything-is-an-object-what-does-that-mean)
- [But what about rails? How this framework applies that concept for maximum developer experience](#but-what-about-rails-how-this-framework-applies-that-concept-for-maximum-developer-experience)
- [How to define methods dynamically](#how-to-define-methods-dynamically)
- [Using hooks to detect moments on the instantiation of the class](#using-hooks-to-detect-moments-on-the-instantiation-of-the-class)
- [Conclusion](#conclusion)

Como você pode ver, a ideia geral para definir a segunda parte do link é incluir uma hashtag # junto ao título em um formato especifico seguindo as regras:

• Trocar todos os espaços em branco por hifens -
• Deixar todo o título em minúsculo

E é isso! Títulos com acentos podem continuar igual sem nenhum problema, o Markdown compreende como texto padrão igual mostrado abaixo:

- [Um título com muitos acentos e çedilha](#um-título-com-muitos-acentos-e-çedilha)

A estrutura básica de um artigo técnico

Agora que temos uma noção interessante de como podemos marcar nosso texto para ficar legível e agradável de ler, vamos entender um pouco a estrutura de um artigo. É importante ressaltar que um modelo não vai servir para todo tipo de texto possível, a ideia é prover uma ideia geral que deve ser adaptada e mudada conforme o contexto.

Primeiro é muito importante definir o parágrafo inicial para chamar o leitor para o problema ou a situação que você vai dissecar ao longo do artigo, é importante fazer isso, pois esse primeiro paragrafo vai ser usado pelo dev.to para comunicações de marketing por e-mail ou por redes sociais. Um exemplo de parágrafo inicial pode ser achado nesse mesmo artigo que você esta lendo ou em alguns outros que deixo abaixo:

A ideia é sempre utilizar perguntas e pausas no texto para podermos alcançar uma comunicação direta e bem conversacional, sempre tentando apresentar a situação da maneira mais geral possível para que quem esteja lendo fique com bastante curiosidade e vontade de ler.

Após o primeiro parágrafo de apresentação, é muito importante definir a Tabela de conteúdo para guiar o usuário ao longo dos títulos principais do seu artigo, sobre isso inclusive eu particularmente não recomendo listar os subtítulos junto dos títulos por conta de deixar a tabela de conteúdo muito grande e pouco útil para quem estiver lendo, obviamente que se você considerar seus subtítulos muito importantes de serem listados é completamente valido incluir.

Passando para o corpo geral do artigo, entramos em uma área muito subjetiva, pois depende muito do assunto que está sendo abordado para entender a estrutura dos seus títulos e parágrafos. Vou assumir um artigo no modelo de tutorial simples para ser possível partir de algum lugar.

Recomendo sempre ter três títulos satélites que vão nortear o seu artigo e dar inspiração para aumentar o conteúdo com mais detalhes. Esses títulos satélites são os seguintes:

• Introdução a tecnologia ou problema: Esse parágrafo vai servir para podermos detalhar o que foi falado no começo do artigo, respondendo às perguntas que criamos para atiçar a curiosidade e aprofundando mais no tema que vai ser discutido com os tópicos específicos.
• Prós e contras: Nesse momento vamos deixar claro os prós e contras da solução que vai ser apresentada no artigo, seja ela uma arquitetura, um padrão de código, uma linguagem, framework, etc. A existência desse paragrafo pode ser bem situacional dependendo do seu tema, mas costuma ser bem útil caso esteja apresentando uma solução em forma de tutorial!
• Conclusão: Esse ponto é mais uma opinião do que uma regra geral, mas eu acho muito importante ter um parágrafo onde vai ser indicado o final do processo de leitura, assim podemos deixar argumentos finais, agradecimentos, contato e qualquer outra mensagem interessante.

Ao redor desses três principais títulos, podemos desenvolver nosso artigo com uma escrita ilustrativa e que apresente exemplos práticos ou analogias, facilitando a visualização tanto do problema quanto da solução pelo leitor. É importante ressaltar também o cuidado ao aprofundar muito nas analogias, elas são extremamente uteis, mas podem ser um tiro no pé quando você abusa e nunca volta para o mundo real com uma solução e explicação clara.

Uma dica geral ao redor da estrutura do artigo é manter o sentimento geral da leitura leve, portanto é super aconselhável utilizar imagens (seja um meme para descontrair ou um gráfico para ilustrar melhor o ponto apresentado), como a plataforma do dev.to comporta artigos técnicos mais informais, abusar dessa linguagem mais próxima é uma estratégia muito certeira.

Como revisar e melhorar a escrita

Bom, agora que temos uma boa ideia de como estruturar nosso artigo, como mantê-lo bonito utilizando Markdown e como ponderar nossa linguagem para a plataforma especifica, o que falta? Bom, agora o que falta é entender que não somos perfeitos e erramos, portanto, precisamos de uma boa estratégia para revisar o artigo que acabamos de produzir com nossas técnicas aprendidas.

Para auxiliar na escrita, eu recomendo fortemente utilizar um editor que oferece visualização do Markdown em tempo real como VSCode ou o queridinho da comunidade Obsidian. Inclusive esse artigo foi escrito utilizando o Obsidian!

No que se entende por revisão temos algumas ferramentas bem interessantes que nos auxiliam em diversos aspectos da escrita:

• LanguageTool: Essa ferramenta é meu xodózinho e ela cuida de toda correção de ortografia, a parte legal é que nessa ferramenta você pode ter dicas de contexto que vão melhorar a frase e também correção de termos específicos de programação como nomes de linguagens visto que o banco de dados deles é super atualizado.
• Deepl: Entrando no mundo das inteligências artificiais, o Deepl utiliza deep learning para oferecer uma interface incrível de tradução, mas não só isso! Com ele podemos ter uma segunda opinião para refrasear nosso parágrafo de forma muito simples, você só precisa traduzir o texto para inglês e traduzir o texto em inglês para português de novo; normalmente no Google Translate isso destruiria o contexto, mas essa ferramenta mantém o contexto e melhora as expressões para que você possua uma segundo percepção de um mesmo paragrafo.
• ChatGPT ou Bard: Bom, aqui eu confesso que não tenho muito domínio e não uso tanto, mas essas interfaces de chat com IA ajudam muito a ter visões diferentes para refrasear um parágrafo já existente ou até mesmo começar a escrever algum. Importante: Preciso ressaltar para usar essas ferramentas apenas para ter ideias ou ajudar a refrasear textos que você já escreveu, por favor não produza artigos inteiros utilizando inteligência artificial
• Comunidade: Na comunidade He4rt Developers tentamos providenciar o máximo de auxílio para a escrita de artigos técnicos na plataforma dev.to. Fazemos isso providenciando um fórum onde você pode postar seu artigo ainda em progresso e ganhar feedback da comunidade até a publicação, após a publicação a gente ainda faz um trabalho de divulgação para pessoas ativas! Disclaimer: Obviamente estou citando a He4rt, pois temos um projeto voltado para isso, mas a lição geral é compartilhar seus progressos com a comunidade de maneira geral.

Conclusão e agradecimentos

Esse é o último artigo que estou postando seguindo o desafio 100 dias de código, foi um desafio muito intenso e com muito aprendizado onde eu descobri uma nova paixão: escrever e compartilhar conhecimento! Não tenho nem palavras para agradecer a comunidade da He4rt por ter me apoiado 100% nessa jornada imensa. Espero que esse artigo seja útil para quem esteja lendo e que inspire qualquer um a compartilhar conhecimento online para podermos criar uma internet mais segura e rica em informação.

Gostaria também de deixar um agradecimento especial aos revisores desse artigo:

• Anibal Sólon
• Alicia Marianne
• Miguel S. Barbosa
• Clinton Rocha
• Samuel Rodrigues

May the force be with you! 🍒