Por que este blog existe

Quando eu terminava um projeto, o código permanecia, mas boa parte do raciocínio desaparecia. A tentativa que falhou, a restrição que mudou a arquitetura e o teste que desmentiu uma hipótese ficavam espalhados entre anotações, issues e histórico do Git. Este blog existe para reunir esse material de uma forma que outra pessoa consiga acompanhar.

O resultado sozinho escondia as decisões

Uma funcionalidade pronta mostra o que ficou. Ela não mostra por que uma alternativa foi descartada, qual problema apareceu durante a implementação ou o que precisou ser simplificado para a entrega acontecer.

Isso ficou evidente nos meus projetos. No DocAuto, trocar o motor de conversão alterou custo e fidelidade dos documentos. No project-smaug, um erro de interpretação dos dados levou à separação entre a ingestão bruta e o cálculo dos indicadores. No formulário deste site, usar o Discord como caixa de entrada eliminou a necessidade de manter um painel próprio, mas criou uma dependência externa que a API precisa tratar.

Essas decisões explicam melhor meu trabalho do que uma lista de tecnologias.

Os textos partem de algo que foi construído

Os assuntos do blog vêm de projetos, estudos e problemas que encontrei durante o desenvolvimento. O objetivo não é publicar uma resposta definitiva sobre cada tema. É registrar o contexto suficiente para mostrar o que foi feito e onde a conclusão ainda tem limites.

Um texto pode apresentar:

• a arquitetura de um sistema e a razão de cada fronteira;
• uma tentativa que não produziu o resultado esperado;
• a comparação entre duas ferramentas ou abordagens;
• um teste que confirmou ou invalidou uma hipótese;
• uma decisão que eu tomaria de forma diferente hoje.

Quando houver uma medição, ela deve aparecer. Quando houver apenas uma hipótese, ela precisa ser identificada como hipótese. Essa separação é especialmente importante nos textos sobre inteligência artificial, onde uma demonstração convincente nem sempre representa um comportamento confiável em outros casos.

Escrever também melhora a revisão do trabalho

Explicar uma decisão obriga a reconstruir a sequência que levou até ela. Às vezes, o motivo continua válido. Em outras, percebo que apenas me acostumei com a solução e nunca registrei a restrição que a justificava.

O texto cria uma revisão posterior. Ele permite comparar o que eu esperava com o que o projeto realmente entregou e deixa os custos da escolha visíveis. Isso é útil para quem lê, mas também para mim quando volto ao mesmo problema meses depois.

Para quem estou escrevendo

Os textos são voltados principalmente a pessoas que trabalham ou estudam engenharia de software. Não parto do pressuposto de que o leitor conhece o projeto ou as ferramentas mencionadas. Sempre que um conceito for necessário para acompanhar o raciocínio, ele deve ser apresentado no próprio texto.

O que pretendo oferecer é um caso concreto: o problema, as alternativas, a decisão tomada e o resultado observado. O leitor pode aproveitar a solução, questioná-la ou apenas evitar uma tentativa que já mostrou suas limitações.

Ainda estou descobrindo quais formatos funcionam melhor e quais assuntos merecem continuidade. O critério para publicar, porém, está definido: cada texto precisa mostrar algo que aconteceu de fato e explicar por que aquilo mudou o trabalho.