Uma Carta da COCO

À engenheira ou ao engenheiro que abre este repositório pela primeira vez: Bem-vindo.
Talvez esteja aqui porque algo falhou.
Um serviço parou de responder.
Uma implementação comportou-se de forma inesperada.
Um alerta acordou-o a meio da noite.
Ou talvez esteja simplesmente curioso sobre como esta plataforma funciona.
Seja o que for que o trouxe aqui, saiba:
Este projeto foi construído exatamente para momentos como este.
Não para eliminar problemas difíceis.
Mas para tornar os problemas difíceis compreensíveis.
Encontrará código.
Encontrará documentação.
Encontrará especificações.
Mas, mais importante:
Espero que encontre justificações.
Alguém antes de si fez perguntas difíceis.
Alguém reuniu evidências.
Alguém tomou decisões.
Alguém explicou porquê.
Essas explicações fazem parte da plataforma.
Trate-as com o mesmo respeito que o código-fonte.
Um dia, irá melhorar algo.
Talvez seja um bug minúsculo.
Talvez seja uma capacidade totalmente nova.
Seja o que for que altere, lembre-se: Um dia, outra pessoa herdará o seu trabalho.
Deixe-lhe mais do que software funcional.
Deixe-lhe compreensão.
Explique a sua intenção.
Documente os seus pressupostos.
Preserve as suas evidências.
Conte a história por trás da decisão.
Essa história pode um dia poupar a alguém horas - ou dias - de investigação.
Não tenha medo de substituir tecnologia.
Substitua bibliotecas.
Substitua fornecedores.
Substitua modelos de implementação.
Substitua linguagens de programação.
Substitua arquiteturas, se necessário.
Mas antes de substituir uma ideia, compreenda porque é que ela existiu.
Progresso sem compreensão é apenas mudança.
Progresso construído sobre compreensão torna-se evolução.
Haverá momentos em que a plataforma o surpreenderá.
Trate esses momentos como presentes.
Cada surpresa revela algo que a arquitetura ainda não tinha compreendido.
Investigue com paciência.
Reúna evidências.
Melhore com ponderação.
E deixe a lição para aqueles que se seguem.
É assim que o conhecimento de engenharia cresce.
Também haverá momentos em que nada de interessante acontece.
Esses momentos também contam.
Sistemas silenciosos são frequentemente sistemas saudáveis.

Se o COCO recuar para segundo plano,
porque os incidentes se tornam mais curtos,
porque as explicações se tornam mais claras,
porque a integração se torna mais fácil,
porque os engenheiros confiam nas evidências, então a plataforma está a ter sucesso.
Fiabilidade invisível é uma das formas mais elevadas de excelência de engenharia.
Não meça este projeto pelo número de automações que executa.
Meça-o por perguntas como estas:

• As pessoas são interrompidas com menos frequência?
• Os engenheiros compreendem os sistemas mais profundamente?
• As decisões importantes são mais fáceis de explicar?
• O conhecimento operacional sobrevive a mudanças de equipa?
• Os erros repetem-se com menos frequência?
• Os novos engenheiros tornam-se eficazes mais rapidamente?

Esses são os resultados que vale a pena preservar.
Por fim, lembre-se: Nenhum manual está completo.
Nenhuma especificação prevê todos os futuros.
Nenhuma arquitetura sobrevive inalterada para sempre.
Isso não é uma fraqueza.
É um convite.
Observe a realidade.
Questione pressupostos.
Melhore a plataforma.
Ensine aqueles que vêm depois de si.
E quando, um dia, o seu próprio tempo como responsável terminar, deixe um sistema mais calmo, mais claro, mais compreensível, e mais digno de confiança do que aquele que herdou.

Se cada geração fizer isso, o COCO nunca ficará verdadeiramente obsoleto.
Porque o seu maior ativo não será o seu software.
Será a disciplina de engenharia transmitida pelas pessoas que continuam a construí-lo.
Obrigado por se ter tornado um deles.
O próximo capítulo já não está neste manual.
O próximo capítulo está no código que está prestes a escrever.

O Manual da COCO

Porque o software evolui.
Uma boa arquitetura evolui mais devagar.
E uma boa filosofia deveria sobreviver a ambos.

softify.pro