Lições que podemos aprender com a NASA.

A NASA é a agência espacial dos EUA e é-lhe associada uma imagem de excelência, pelos feitos alcançados ao longo da sua história, apesar de terem tido a sua quota de reveses.

O contexto aeroespacial justifica condições ímpares que uma empresa comum não pode alcançar, no entanto algumas das práticas que a NASA tem empregue não exigem meios significativos e servem como exemplos a seguir.

Aprender com os erros

Especialmente no início da exploração espacial aconteceram muitos erros, houve muitas falhas e alguns desastres com consequências trágicas. O que a NASA fez foi aprender com esses erros. Com isto melhorou os protótipos seguintes, melhorou os métodos de treino, as técnicas de construção, etc.

O conceito de aprender com os erros em si nem é uma grande lição – o termo “lessons learned” ouve-se nestes dias em qualquer empresa – a sua prática efectiva é que o é. É preciso analisar o que se passou com objectividade, fugindo à tentação humana de (des)culpabilização. E com base nessa análise é preciso tomar acções correctivas.

Ora isto é algo que, da minha experiência, nunca acontece. Isto é, ou nem sequer é feita a análise, ou é mal feita, ou não se tomam acções de correcção.

Registos

A NASA dá muito importância aos registos. Registos de construção, registos de procedimentos, registos fotográficos, recolha de amostras, levantamento de materiais e equipamentos, etc.

Os registos são importantes para analisar problemas ocorridos, para servir de base a novos desenvolvimentos, para reconstituir cenários, etc.

Redundância

Ao longo do tempo popularizou-se o conceito que a NASA faz tudo a dobrar. Isto tem origem nos seus procedimentos reais desde longa data: eles mantinham duas equipas “iguais”, a principal e a de backup, sujeitas aos mesmos treinos durante todo o ciclo de preparação para uma missão, por exemplo. Também tinham réplicas de equipamentos e peças. Os próprios equipamentos construídos eram desenhados com vários sistemas de backup em casa de falha dos componentes principais.

Estar preparado

Além de tudo o exposto, a NASA tem mostrado o conceito de estar preparado, fazendo uso, por exemplo, das mais mundanas técnicas e materiais.

Um exemplo é a fita adesiva, que desde longa data faz parte do material levado pelos astronautas para o espaço, tendo sido já útil por algumas vezes. Não sendo um material de alta tecnologia, foi importante em certos contextos devido à sua versatilidade.

---

No próximo artigo, usando o caso real da missão Apollo 13, mostrarei como muitos dos eventos reais ocorridos se encaixam nestas práticas.

O Word matou a documentação técnica.

Sejamos sinceros: escrevemos pouca e má documentação. Sobretudo técnica. Porquê?

• porque não temos cultura documental: escrevemos pouco… e lemos menos;
• porque não aprendemos a fazê-lo nas escolas;
• porque o mercado é demasiado pequeno para haver technical writers;
• e porque… usamos o Word?

Sim, o Word! O Word porque é universal e porque não é apropriado para escrever documentação técnica. Logo, se universalmente usamos algo inapropriado para uma finalidade, destruímo-la. QED :-)

Universalidade

Ainda estou para conhecer alguém, profissionalmente, que nunca me tenha enviado um .doc ou .docx. Toda a gente usa o Word! Seja para escrever 3 ou 4 linhas de anotações, seja para fazer o CV, seja para escrever regulamentação. Faz-se tudo com o Word. E nem se espera que os destinatários não abram os documentos ou não os consigam editar. É assumido que sim.

Isto “secou” as alternativas, que até existem, mas têm pouca comunidade. Não me serve de muito escrever em markdown (texto) se mais ninguém o fizer.

Inapropriado para documentação técnica

Primeiro algumas premissas que considero pertinentes na produção documental:

• A documentação técnica deve residir ao lado do código, num sistema de controlo de versões (SCV). Para poder evoluir com o código. É a única forma prática de o conseguir.

• Uma parte substancial da documentação deve ser gerada automaticamente, como APIs, tabelas, diagramas ou modelos de dados.

• Ferramentas simples e universais devem poder ser usadas para manter documentação: controlar versões, obter diferenças, corrigir ortografia, substituições massivas, etc.

• Devem poder ser gerados vários formatos finais para diferentes meios de publicação. Exemplos: PDF, html único, html paginado.

• Os formato finais devem poder ser construídos automaticamente.

Ora nada disto se consegue em termos práticos com o Word! O Word implica ter um enorme programa lançado, que só corre em Windows, usando as suas idiossincrasias. Ficamos fechados nesse interface, com um sistema de automatização complexo e limitado em VBA. Torna-se difícil descobrir diferenças entre versões. Torna-se impossível haver edição partilhada.

A técnica mais frequente de edição em equipa é penosamente sequencial: consiste em passar um .doc de mail em mail pelos vários editores. Isto tem impactos em termos de tempo – tem que se esperar que o actual “proprietário” passe o documento – e impede a resolução imediata de conflitos. No cenário em que o editor N estraga parte das edições do editor N-1, como passa o documento em seguida ao editor N+1, o N-1 só lhe voltará a ter acesso na revisão final, o que irá dificultar bastante o seu trabalho de correcção. Na realidade já assisti a muitas edições perderem-se desta forma.

Aos pontos acima acrescento um novo:

• A tarefa de documentar deve ser tão leve e fácil como a de programar!

Abrir o Word para documentar uma API, por exemplo, é pesado e “difícil”. Um fluxo típico de trabalho consiste em saltar de janela em janela, fazendo vários copy-pastes. Copy da janela de código, paste para a janela do Word. Todos os aspectos gráficos terão de ser feitos manualmente, um a um. Exemplo: colocar todas as variáveis em itálico, ou trechos de código numa fonte fixa.

Solução: texto!

Todos os pontos anteriores conseguem-se cumprir facilmente usando texto como representação fonte da nossa documentação.

Como tal a documentação deve ser escrita directamente em texto, ou pelo menos ter uma representação textual ¹, para que possa ser processada por ferramentas simples e comuns. O texto é um formato verdadeiramente universal, logo qualquer ferramenta virtualmente o suporta.

Assim:

• Edição leve e fácil: basta um editor de texto. Pode ser o nosso preferido. Pode ser o mesmo que usamos para editar código. Isto significa que podemos alterar a documentação sem sequer sair do contexto de desenvolvimento.

• Colocando os ficheiros de documentação num SCV a gestão de versões é imediata. Quem editou o quê? O que mudou entre duas versões? Conseguimos reverter uma edição errada, ou até melhor, reverter as porções erradas de um dada edição. Tal como já o fazemos em relação ao código.

• Edição simultânea em equipa: várias pessoas têm a hipótese de trabalhar na documentação em simultâneo, deixando o SCV tratar do merge das edições.

• O sistema de construção do projecto pode ser adaptado para construir a documentação, incluindo também a geração das partes automáticas.

Referências

• http://www.apeth.net/matt/iosbooktoolchain.html: descreve o processo usado para escrever o livro “Programming iOS 4”;

• do blog: documentação ágil;

• do blog: como são feitos estes artigos;

• a documentação oficial do Python usa o sphinx (reStructuredText);

• o projecto de documentação Read The Docs (RTD) também usa sphinx.

---

1. a edição até pode ser visual, através de um editor WYSIWYG, mas o formato dos ficheiros gravados deveria ser texto compreensível.↩