Documentação para o teu eu do futuro:retorno de 18x

Quando constróis sozinho, a documentação não é para outras pessoas: é documentação para o teu eu do futuro, e o teu eu do futuro esqueceu-se de tudo. Dez minutos de notas quando construí uma funcionalidade teriam poupado as três horas que passei mais tarde a fazer engenharia inversa à minha própria base de dados. É um retorno de 18x, numa só funcionalidade.

A documentação parece o hábito mais corporativo e mais dispensável que um solopreneur podia adotar. É o contrário: é o hábito que permite a uma empresa de uma só pessoa comportar-se como uma equipa — porque a pessoa que escreveu o código há seis meses é, na prática, outra pessoa.

O dia em que me esqueci do esquema da minha própria base de dados

Três meses antes, tinha construído uma funcionalidade complexa para a minha plataforma de aceleração. Base de dados com várias tabelas, cuidadosamente estruturada, políticas de segurança, tudo a que tinha direito. Levou seis horas a desenhar e implementar, e eu estava orgulhoso dela.

Depois precisei de acrescentar um campo a essa funcionalidade. Abri o código, olhei para as tabelas, comecei a ler — e não fazia a mínima ideia porque é que tinha tomado certas decisões. Porquê quatro tabelas de ligação em vez de duas? Porque é que esta coluna é opcional? Porque é que esta regra de acesso verifica duas coisas em vez de uma?

Passei três horas a fazer engenharia inversa ao meu próprio código. Não ao de outra pessoa. Ao meu. Nenhuma nota sobre a funcionalidade, nenhuma explicação do desenho, nada que mostrasse como as peças se relacionavam. Só código, e uma memória que tinha apagado tudo em silêncio.

Numa equipa, as decisões são discutidas e o conhecimento é partilhado. A solo, há exatamente uma cópia do «porquê» — na tua cabeça — e expira mais depressa do que pensas. É esse o custo escondido do desenvolvimento a solo, e quase ninguém o contabiliza.

Documentação para o teu eu do futuro: as contas

Dez minutos de documentação quando construí essa funcionalidade teriam poupado três horas mais tarde. Retorno de 18x, uma funcionalidade. Agora escala isso: tenho 45 funcionalidades em produção. Se documentar à partida poupa cerca de duas horas por funcionalidade ao longo do tempo, são 90 horas por ano — 7.200 € do meu tempo a 80 €/hora, comprados com dez minutos por funcionalidade.

As contas ao longo da vida útil são ainda mais desequilibradas. Pega numa funcionalidade ao longo de dez alterações futuras:

Cerca de 18 horas poupadas por funcionalidade ao longo da sua vida útil. Em 45 funcionalidades, são 815 horas — 65.200 € de valor a 80 €/hora. Mas, sinceramente, o dinheiro não é o que importa. O que importa é o que a documentação te deixa fazer: refatorar sem medo porque sabes o que vai partir, construir sobre trabalho anterior porque te lembras dos teus próprios desenhos, e depurar em minutos porque as armadilhas estão escritas.

O livroThe Solopreneur RevolutionLuis Gonçalves sobre como construir um negócio de EUpreendedor com IA sem deixar o emprego.Quero o livro →

Os quatro documentos de que cada funcionalidade precisa

Depois de 45 funcionalidades, assentei em quatro tipos de documentação, por ordem de importância.

Documentação do porquê — o contexto de negócio. A mais importante e a mais saltada. Que problema resolve esta funcionalidade, que impacto tem e porque tomaste as principais decisões de desenho? É este o documento que impede o teu eu do futuro de «otimizar» uma decisão que existia por uma razão. Enquanto arquiteto do teu produto, as tuas decisões são o único ativo que não pode ser regenerado — escreve-as.

Documentação do quê — como funciona. As tabelas envolvidas, como os dados circulam pela funcionalidade, o que acontece e por que ordem. É este o documento que responde a «porquê quatro tabelas de ligação?» em trinta segundos em vez de três horas.

Documentação do como — o guia de utilização. Como tu (ou, um dia, alguém do suporte) operas de facto a funcionalidade: onde se configura, o que os utilizadores veem, quais são os passos.

Documentação das armadilhas — as notas de resolução de problemas. Cada armadilha que já te mordeu: a definição que parece avariada mas é só lenta, os dados que têm de existir antes de algo funcionar, a solução para o erro que vais de certeza ver outra vez. Cada entrada poupa uma futura sessão de depuração.

Torna a documentação automática

Eis a objeção honesta: não quero gastar nem dez minutos por funcionalidade a escrever documentação à mão. É aborrecido, e é tempo que não passo a construir. Antes da IA, essa objeção ganhava — a documentação levava duas a três horas por funcionalidade, por isso eu saltava-a.

Com a IA, o atrito desapareceu. Cada funcionalidade que construo começa num briefing estruturado — um PRP — que já contém o objetivo, as decisões de desenho e as armadilhas. Quando a funcionalidade é lançada, a IA transforma esse briefing em documentação em cerca de dez minutos. Completa, consistente, e nunca salta secções por aborrecimento.

Depois, uma regra mantém o hábito vivo: se lanço código sem documentação, não lancei. A minha checklist impõe-no — funcionalidade, testes, documentação, as três ou não entra no merge. Não consigo contornar a minha própria regra, que é precisamente a questão.

O resultado: mais de mil páginas de documentação pesquisável, escrita sobretudo pela IA, a cobrir cada funcionalidade do produto. Desde então, zero momentos de «em que é que eu estava a pensar?». E quando contratar o meu primeiro engenheiro, ele herda tudo isto no primeiro dia — duas semanas de avanço na integração que a maioria das empresas construídas a solo simplesmente não tem.

12 semanasA tua carreira corporativa nunca foi o planoCandidata-te ao Solopreneur Accelerator.Candidatar-me →

Perguntas frequentes

Porquê documentar um projeto em que só eu trabalho?

Porque daqui a seis meses és, para todos os efeitos, outra pessoa. Passei três horas a fazer engenharia inversa à minha própria base de dados porque não documentei nada. A documentação a solo não é burocracia — é uma mensagem do teu eu do presente para o teu eu do futuro, e o teu eu do futuro lê-a sempre com gratidão.

O que devo realmente documentar?

Quatro coisas por funcionalidade: porque existe e porque tomaste as principais decisões; o que faz tecnicamente; como se usa; e as armadilhas que já te morderam. Se só escreveres uma, escreve o porquê — é a única parte que o próprio código nunca te pode dizer.

Quanto tempo demora a documentação com IA?

Cerca de dez minutos por funcionalidade. Se constróis a partir de um briefing estruturado, a IA gera a documentação a partir de material que já existe — é uma conversão, não um projeto de escrita. O custo antigo era de duas a três horas por funcionalidade, e é por isso que ninguém o fazia.

Qual é o retorno de documentar enquanto fundador a solo?

Os meus números: dez minutos de documentação contra três horas a reaprender dá 18x numa só alteração. Ao longo da vida útil de uma funcionalidade são cerca de 18 horas poupadas; nas minhas 45 funcionalidades, cerca de 815 horas — 65.200 € a 80 €/hora. Mais a parte que não tem preço: a confiança para alterares o teu próprio código sem medo.