O livro de receitas da itexto

Escrever software é difícil: mantê-lo ainda mais. Neste post apresento uma técnica que nossa equipe aplica internamente, recomendamos a nossos clientes e que abrimos agora ao resto do mundo: o livro de receitas.

A ideia parece simples, é simples (quase óbvia) porém poucas equipes a aplicam. Neste post vamos conversar um pouco a respeito disto.

O que é um livro de receitas?

No dia a dia sempre surgem momentos nos quais você não consegue prosseguir na execução das suas tarefas devido a pequenos detalhes. São normalmente dúvidas bem simples: como exponho um serviço executado em minha máquina para o cliente testar? Como gero uma branch a partir de um commit? Como resolver o erro xpto que aparece quando executo o backup do MySQL?São pequenos conhecimentos, triviais para os mais experientes, ocultos para os iniciantes, que impactam e muito a produtividade das equipes. Então por que não ter um local no qual documentemos estes conhecimentos para que na repetição dos problemas possamos usar esta base de conhecimento como referência?

O livro de receitas é este “local” no qual você documenta estes procedimentos para que outras pessoas não sofram o que você sofreu até descobrir como resolver aquela situação.

Como criamos nosso livro de receitas

O livro de receitas pode assumir as mais variadas formas. Nossa primeira versão era uma pasta compartilhada no Google Docs na qual colocávamos pequenos textos que ilustravam estas questões. As limitações deste formato rapidamente se apresentaram: conforme nosso conteúdo aumentava, categorizar o conteúdo ia se mostrando mais difícil. Poderíamos ter uma pasta por assunto, mas muitas receitas tangem mais de um assunto.

A segunda iteração foi um wiki. No caso usamos o que o Redmine provê e nos atendeu por um bom tempo. Era mais fácil encontrar o material, entretanto o problema da categorização ainda se mantinha. Colocávamos páginas que eram índices e, nestes índices, chegávamos ao assunto. Não só isto: havia momentos em que precisávamos aplicar um estilo ou imagem e ele não nos atendia tão bem quanto gostaríamos.

Finalmente veio a terceira iteração: adotamos o WordPress como solução e esta tem sido sua forma desde então. O WordPress atendeu diversos dos nossos requisitos essenciais e mais alguns:

• O editor é excelente (especialmente o baseado em blocos).
• Os mecanismos de busca são bem interessantes também, melhores que os das iterações anteriores.
• Fácil de usar: em cinco minutos quem precisa escrever algo já pega o jeito da coisa.
• Permite controlar o acesso ao conteúdo de forma fácil. Nosso livro de receitas é e continuará sendo privado por razões que vocês entenderão melhor adiante neste post.
• A categorização é super adequada: podemos ter mais de uma categoria associada a um post.
• Nos permite ver como está crescendo nosso conteúdo na medida em que apresenta quantos posts foram criados por mês.

Resumindo: WordPress foi a melhor solução que poderíamos encontrar.

Mas há um outro fator importante neste livro de receitas: todos da equipe deve ter acesso a seu conteúdo. O objetivo é compartilhar soluções.

E o compartilhamento de soluções é a forma mais eficiente que conheço de reuso.

Como escrevemos as receitas

A receita deve ser simples: curta e direta. Essencialmente é composta por duas partes apenas:

• O problema a ser resolvido: descrito em no máximo três frases.
• A solução para o problema, que não deve ser muito longa também.

A concisão aqui é fundamental: ela torna claro a todos o problema que deve ser resolvido e já delineia o escopo do texto que escreveremos a seguir. Também apresenta um outro ganho inesperado: normalmente quando o autor da receita escreve títulos enormes este é o momento em que percebe que de fato não conhece o problema cuja solução deseja descrever (muito interessante isto!).

Já quanto à solução o ideal é que seja o mais simples possível. Pode se manifestar de qualquer forma:

• Um passo a passo pra solução do problema.
• Trechos de código fonte que exponham a solução do problema.
• Um texto rápido explicando a solução.
• Não raro apenas um link que aponte para outro lugar que contém a solução.
• Uma imagem, vídeo, áudio. Há situações em que é simplesmente um arquivo com sua descrição ultra sucinta.

A linguagem não precisa ser shakespeariana. Não precisa ser um Machado de Assis, o importante é que você consiga transmitir a ideia e rápido para que seus colegas resolvam o mais prontamente possível aquele problema.

Vamos a um exemplo de receita então?

Um exemplo rápido

Erro mysqldump: Unknown table ‘COLUMN_STATISTICS’ in information_schema (1109)

Se deve à versão 8 do mysqldump ter uma nova flag padrão que busca por esta tabela, mesmo em versões anteriores do MySQL que ainda não a tenham.

Fácil de resolver: apenas forneça o parâmetro –column-statistics=0 ao mysqldump que o backup funcionará normalmente.

Mais detalhes neste link: https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html#option_mysqldump_column-statistics

Comentando o exemplo

Note como o exemplo é simples: o título mostra o problema que você enfrentou. Colocamos inclusive o código de erro ali, o que facilita a busca caso necessário.

O post também é categorizado. Neste caso, criamos uma categoria “MySQL” e outra chamada “Backups”. Assim fica fácil encontrar posts sobre estes assuntos.

E finalmente a descrição é simples, coloquial, e curta. Os colegas entendem o texto e facilmente aplicam a solução. E justamente por ser uma linguagem coloquial é que não recomendo que seu livro de receitas não seja público. Não raro alguém pode pode escrever alguns xingamentos ali (eu mesmo xingo bastante). 🙂

Além disto o fato de ser privado torna o ato de escrita mais convidativo para toda a equipe. Não são todos que querem ter seus textos publicados para que qualquer um os leia por aí. Isto sem mencionar que não raro alguém pode publicar algo errado ali. É papel da equipe aplicar as correções nos textos conforme aplicáveis.

Finalmente, notou que tem uma imagem ali? Ela é totalmente opcional: a coloquei apenas por que não raro os membros da equipe acessam com frequência este blog, então fica fácil identificar visualmente sobre o que aquela receita se refere.

Benefícios adicionais

O benefício óbvio é a função do livro de receitas, mas há outros ganhos que vale muito à pena mencionar.

O primeiro deles é o incentivo à escrita. Nossa experiência mostra que os melhores desenvolvedores são também aqueles que normalmente mais gostam de ler e, principalmente, escrever.

Isto porque o ato da escrita na prática é a externalização do nosso conhecimento. E você só consegue ter certeza de que realmente conhece algo se consegue descrever este algo por escrito e outras pessoas conseguem te entender.

(E o que é o ato de escrever se não a externalização em código do conhecimento que adquirimos a respeito do mundo?)

Outra vantagem é a produtividade imediata. Quando alguém enfrenta um problema já conhecido, o envio de um link já resolve a questão na hora, poupando com isto um bom tempo.

Observamos também que a confiança dos autores do livro de receita também aumenta com o tempo. Provavelmente devido à gratificação que é ver seus colegas prosperando graças à sua contribuição.

Mais que a confiança, é também um exercício que aumenta bastante o próprio sentimento de união do time. Quando uma mão lava a outra tudo fica muito mais fácil.

E agora vamos abrir o nosso livro de receitas para vocês!

Nosso livro de receitas já tem cinco anos de posts publicados e toda semana tem novos conteúdos. A exposição ao público geral deste material era vista como uma possibilidade remota, porém recentemente relendo alguns dos posts percebemos que muitos deles deviam ser publicados pois muitas pessoas que trabalham com desenvolvimento enfrentam estes problemas.

Sendo assim aguardem nossas postagens no blog da itexto. Semanalmente iremos elencar uma de nossas receitas privadas, lhe aplicar a maquiagem necessária para que possa se tornar pública e a publicaremos aqui.

Espero que esta ideia do livro de receitas lhe incentive a trilhar este caminho com sua equipe. Para nós tem sido uma experiência simplesmente maravilhosa.