Tempos modernos de tecnologia

Em tempos modernos onde a tecnologia possibilita o surgimento de novas ferramentas, bibliotecas e frameworks a cada dia, tem se feito cada vez mais necessário uma documentação bem estruturada e definida sobre softwares desenvolvidos. Sejam eles soluções complexas e em constante evolução, ou mesmo uma pequena aplicação específica para um determinado nicho de mercado.

O importante é transmitir de forma clara e objetiva as características de seu produto, a melhor forma de implantação, o modelo que melhor se adequa e atende a necessidade do cliente, os requisitos mínimos necessários para que a aplicação possa rodar sem causar perda de performance ou gerar conflitos. Isso se faz não apenas com um e-mail descritivo sobre os itens que o sistema atende. Ou com um simples documento descrevendo cada tela. Claro que são importantes, mas não podem ser únicos, uma documentação bem desenvolvida, que contenha todos os principais pontos delicados sobre as configurações, ambientes, páginas, módulos, componentes agrega ao produto final muito mais valor.

Mercado aquecido e a falta de mão de obra

Com o mercado tecnológico cada vez mais aquecido e com uma falta de mão de obra capacitada, acaba criando uma grande rotatividade de profissionais qualificados nos times de desenvolvimento. Em projetos de curto prazo esse problema muitas das vezes até passa despercebido, mas em desenvolvimentos mais longos, ou produtos fixos com melhorias contínuas, esse ponto fica bem mais perceptível e acaba deixando um legado muito ruim ao "core" do sistema, deixando cada vez mais difícil seu entendimento e manutenção.

Cada desenvolvedor pensa de uma maneira, tem seus hábitos pessoais muito bem definidos e, como não poderia ser diferente,

cada um tem sua forma de codificar. Não quero aqui entrar no mérito do

Muitas das vezes o desenvolvedor implementa aquela "classe" super moderna, usando todas as novas formas de escritas que a linguagem proporciona, e enquanto ele está "codando", ali fechado no "mundinho" dele, tudo faz sentido, as coisas são claras e simples. Mas algum tempo depois esse cara pode não fazer mais parte do time, ou pior ele mesmo pode não lembrar mais do porque aquele código reage daquela forma.

"Quando Eu fiz, Eu e Deus sabia… Hoje só Deus sabe!"

Já ouvi essa frase algumas vezes na vida. Rs

Mas faz todo sentido em alguns casos, pois a pessoa pode não estar mais na equipe, não documentou, não deixou exemplos, o código não está tão "Clean" assim para ser entendido… Enfim, alguém vai precisar parar para perder um tempo lendo e relendo aqueles códigos até conseguir entender o real funcionamento, para aí então entender o problema e chegar em uma solução.

Essa situação gera um custo muito alto, um stress no time e muitas das vezes no cliente. Quando isso tudo poderia ter sido evitado com apenas algumas linhas de documentação, explicando o contexto geral daquela classe, tela ou componente.

Referências nos dão o caminho

A documentação pode ser desde a própria forma de escrita do código usando um código mais limpo e didático, um readme.md bem escrito detalhando alguns pontos de uso e alguns "porquês" de aquela implementação ter sido feita daquela maneira. Até a construção de um styleguide bem definido, com todas as descrições do sistema, desde os requisitos mínimos para clonar o repositório e rodar, até as definições de paletas de cores, famílias tipográficas, padronização de imagens e molduras.

Partindo do pressuposto que

todo bom programador é preguiçoso, podemos afirmar que quanto mais pronto deixarmos nossas implementações, melhor, mais eficiente e consistente será a aplicação final. Quanto menos trabalho tivermos alinhando botões, nos preocupando com cores e fontes mais tempo teremos para focar na funcionalidade real, na usabilidade, no negócio. Podemos olhar para alguns exemplos de

O que seria do bootstrap se não fosse uma documentação clara, objetiva e muito prática, seu “styleguide”, a sua facilidade de implantação em que um simples Ctrl+C Ctrl+V é possível construir um menu inteiro responsivo com input de busca e auto-complete.

Uma documentação tão bem construída internamente que acabou se estabelecendo como uma das mais usadas bibliotecas de componentes visuais, dando vida a muitas outras aplicações além da grande evolução no produto ao qual foi originalmente criada o Twitter. Chegar a um nível desse, onde os desenvolvedores do time possa, em alguns minutos copiar um "snippet" de código, colar, e já ter um componente pronto, funcional e dentro dos padrões do projeto é um ganho excepcional! Isso gera uma maior produtividade, e possibilita focar os esforços no que realmente vai agregar valor ao produto avançando com novas funcionalidades, e o time não estará preocupado se o formulário do cadastro X está igual ao do cadastro Y.

O importante é a construção da documentação

Existem várias formas de se documentar um sistema, das mais simples às mais complexas o importante é construir algo que seja didático e objetivo, que possa detalhar cada ponto de de cada tela, de cada componente, proporcionando assim um bom entendimento do sistema em menor prazo e isso vai trazer para esse projeto uma menor curva de aprendizado, agilizando a integração de novos colaboradores ao time e ganhando performance no desenvolvimento de novas implementações.