Rafael Dohms Web Engineer

Como escrever artigos técnicos (melhores) em 10 passos

Blogs. A internet nos últimos anos tem visto o crescimento disparado destes sites, desde o desenvolvedor que escreve no finais de semana até o colunista que ganha para fazer isso. E não é por menos, eles são sim uma ótima ferramenta para divulgar seu trabalho e agregar valor ao seu nome no mercado, porém apenas se utilizado de forma correta. Vou me restringir obviamente a falar de blogs sobre tecnologia e desenvolvimento, embora outras áreas tenham muitas historias de sucesso desta plataforma também. Eu realmente não saberia como comentar por exemplo o mercado de esmaltes e como escrever artigos sobre eles.

Recentemente tenho esbarrado com alguns artigos que me deixam na dúvida se seus autores realmente entendem o que é o papel de um blog e de artigos técnicos, ou se o foco deles seria menos honrado e apenas uma forma de atrair mais visitas. Sim, falo do que já conhecemos hoje na internet como ‘flame-baits’ ou seja, iscas para discussões (negativas). São geralmente posts polêmicos, sem embasamento, movidos por uma opinião pessoal e carregados de termos clichê e piadinhas. Menos mal se estes posts fossem apenas ferramentas de autores de blogs pessoais, muito pior quando aparecem em grandes “veículos” de comunicação ou sites especializados.

Dois exemplos me passaram pelo browser recentemente, um artigo gringo sobre PHP x Python, cujo embasamento completo era um tirinha XKCD, um pato e um pedaço de código ilegível. O segundo, brazuca, intitulado PHPog, uma questão de design, publicado recentemente na iMasters. O grande centro do artigo é uma comparação entre PHP OO e Java OO, como as coisas deveriam ser feitas no PHP, e a grande reação dos leitores foi a de que certas coisas no PHP são diferentes e isso não é negativo (tem mais, mas vamos resumir assim). O questionamento é válido, e as discussões sobre a implementação de OO do PHP também, porém o artigo vai além disso, usando temos como o POG (programação orientada a gambiarras) para descrever a implementação e outras formas pejorativas de tratar a linguagem e seus programadores.

Neste ponto mora o problema. Ao agredir a linguagem com piadinhas o resultado esperado pelo post não é mais uma discussão séria sobre o assunto, e sim atrair milhares de fãs sedentos por sangue para defender sua linguagem e retribuir palavras não carinhosas ao autor do artigo. Este foi exatamente o resultado de ambos artigos, sim eles tiveram muitas visitas, sim tiveram muitos comentários, mas isso realmente é bom? Compare 1000 visitas de xiitas revoltados com 200 visitas de pessoas querendo mostrar um ponto de vista diferente sobre um assunto, com qual você aprenderá mais? E a imagem de sua empresa/sua pessoa, como ela vai ficar após esse barulho todo? Pra mim os resultados de ambos artigos poderiam ser muito mais instrutivo, foco na discussões técnicas e menos barulho de “extremistas” e “ativistas” além de exaltarem a imagem dos sites envolvidos por iniciarem discussões de alto nível.

Por isso, uso este meu espaço para ponderar sobre o assunto, e tentar mostrar minha opinião sobre o que seria um artigo técnico bem escrito.

Como escrever artigos técnicos melhores?

1. Evite usar tirinhas cômicas. Sim é divertido, e vai “quebrar o gelo”, mas se você precisa quebrar algum gelo, repense suas intenções com o artigo, elas podem já estar erradas.

2. Fuja de palavras polemicas e pejorativas. Evite usar termos como o POG citado acima, se o artigo fosse chamado “Aplicando Design Patterns usando PHP: qual a melhor forma?” a discussão final teria se focado muito mais em discutir as implementações de OO do PHP do que comentários como “Como se POG existisse só no PHP”, ou “< ?php print “Calma galera” ?>” e até “Nunca vi tanta ignorância incorporada em um único texto.”. Você pode discordar da linguagem e de como algo foi implementado, deve!, porém faça isso com o devido respeito e seriedade.

3. Expresse sua opinião, mas deixe isso claro. Cal Evans uma vez falou que um desenvolvedor só pode ser considerado Sênior, se o mesmo souber se expressar, ou seja, escrever artigos e mostrar seu trabalho e seu raciocínio através disso. Porém ele deve saber também defender suas ideias e mais importante ainda, saber quando admitir o erro. Lembre-se disso, sempre ˜haverá opiniões contrárias, as vezes todas corretas em sua forma, mas as vezes você realmente estará errado, saiba aceitar isso. Atualize o post se for o caso.

4. Pesquise. Estude. Pesquise. Escreva. Mesmo que sempre que você for falar de um assunto o artigo não passe de sua interpretação sobre o mesmo, é sempre uma boa ideia se precaver. Portanto pesquise muito sobre o assunto, procure opiniões contrárias e analise de outros pontos de vista. Caso esteja aberto a admitir o erro depois lembre-se das regras acima, elas irão potencializar uma resposta positiva e o aprendizado.

5. Referências == credibilidade. Se o que você quer explicar se baseia em algum material que leu, faça sempre referências ao material, aponte de onde ele veio, isso trará para o seu conteúdo mais relevância e agregará os argumentos do outro autor aos seus.

6. Quantidade não significa Qualidade. Ter 1001 visitas não significa que seu artigo é bom, ou ruim. Artigos polêmicos, ou sem embasamento e agressivos acabam atraindo muitas visitas, pessoas que querem ver pra acreditar, ou deixar um comentário agressivo. Se o seu objetivo é ter muitas visitas isso realmente funciona, porém qual foi a impressão que as pessoas tiveram de você ao sair de lá? Agora um artigo que deveria divulgar seu trabalho e te projetar como profissional, acabou de mudar a opinião de pessoas para não mais te considerar para uma possível vaga.

7. Não critique, compare. Respeite. Muitas vezes vejo artigos escritos apenas para debochar ou ridicularizar algo, ou a forma como alguém fez algo. Quer fazer algo construtivo? Faça uma comparação sobre como o artigo foi escrito e como ele poderia ser escrito, talvez até de umas dicas de como melhorar. Além de tudo, respeite o profissional que escreveu ou criou aquilo que é alvo de seu artigo, nem todos concordamos em tudo, mas isso não é motivo para chacota e desrespeito.

8. Exemplos práticos. Nem todo tema é passível de um exemplo prático, mas em se falar de tecnologia e desenvolvimento isso geralmente é possível, então faça! Anexe um código, aponte um repositório, um diagrama de classes ou um ERM. Ilustre seu artigo com exemplos e gráficos, a leitura fica mais agradável e coerente.

9. Começo, meio e fim. Pense e planeje seu artigo. Todo artigo tem um objetivo. Para chegar nele o artigo precisa de um começo ou uma introdução, um meio ou o desenvolvimento do tema, e um fim, a conclusão. Isso se aplica a todos artigos, mas também vale pra artigos técnicos. Por exemplo: Descreva o problema que vai resolver, mostre como resolver e conclua se foi ou não uma boa escolha. Garanto que se o seu artigo passa 5 parágrafos contanto a historia do John Armless e no final não explica onde ele se encaixa no tema nem porque, seus leitores vão ficar confusos, e indignados.

10. Don’t be a douchebag. Eu gosto desta frase em inglês por ela ser a forma mais ofensiva sem ser ofensiva de se dizer, não seja um chato. Acalme o ego, baixe a crista, seja sério e respeitoso, receba comentários bem, mesmo os mal educados.

Bem, seguindo minha própria receita, esta é minha opinião, assim são construídos os artigos que eu respeito e gosto de comentar e discutir. Posso estar errado, então por favor comente sua visão do assunto nos comentários, faltou alguma regra? Espero que este artigo possa inspirar artigos melhores de valor técnico e que discussões possam brotar destes.

$facebook->api_client->fql_query("SELECT uid, pic, pic_square, name FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1 = 111111111)");

<?php
	//Get Facebook SDK Object
	$config = array(
	  'appId'  => APP_ID,
	  'secret' => API_SECRET,
	  'cookie' => true,
	);

	$facebook = new Facebook($config);

	//Create Query
	$params = array(
	    'method' => 'fql.query',
	    'query' => "SELECT uid, pic, pic_square, name FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1 = 111111111)",
	);

	//Run Query
	$result = $facebook->api($params);
?>

<?php

namespace App\Facebook;

include_once \ROOT_PATH . 'library/vendor/facebook/facebook.php';

class Client extends \Facebook
{
    private $config;
    private $reqPerms;

    /**
     * Runs a FQL query agains the API
     *
     * @param string $query
     * @return array
     */
    public function fql($query)
    {
        $params = array(
            'method' => 'fql.query',
            'query' =>$query,
        );

        return $this->api($params);
    }

}
$config = array(/* insert config here */);

//Using client
$fb = new App\Facebook\Client($config);

$query = "SELECT uid, pic, pic_square, name FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1 = 111111111)";
$result = $fb->fql($query);

?>