Os 10 mandamentos da documentação

A Toyota é bem conhecida como a organização mais eficiente do planeta, fora do corpo humano, e uma de suas filosofias é evitar a documentação. Em vez de fazer um “processo” para quando alguém na linha de montagem precisa de mais parafusos, eles simplesmente têm 5 caixas de parafusos na prateleira e quando um está vazio eles o movem da prateleira e alguém vem a cada hora e enche todas as prateleiras de trás. Não há necessidade de documentar nada, o processo faz isso por você.

Havia um artigo recente sobre Quartz que falou sobre a atenção da Apple para as listas de verificação.

Acontece que a chave para a criatividade, velocidade e adaptabilidade da Apple é, em sua superfície, exatamente o oposto do tipo de criatividade que se pode esperar. É uma lista de verificação ... muito longa.

O que me fez pensar sobre o que é minha filosofia sobre listas de verificação. Há muita coisa errada com as listas de verificação. Eles ficam desatualizados. Eles podem ser longos e chatos e repetitivos. Como todas as métricas, elas podem se concentrar nas coisas erradas. Mas todas essas coisas são verdadeiras de pular listas de verificação também, certo? Quero dizer, na terceira vez que você cometeu o mesmo erro, provavelmente é hora de admitir que seguir uma lista de verificação pode ter lhe poupado tempo.

Mas as listas de verificação só são boas se forem aplicadas e são atualizadas com frequência, e você ainda está à mercê de um humano que, vamos encarar isso, não é feito para ser perfeito o tempo todo.

Problema do mundo real

Nós temos um padrão Drupal instalar começamos com a maioria dos clientes que estão no Drupal. Isso inclui módulos, configurações, usuários padrão e nossos dados de teste padrão. Costumava ser uma lista de verificação, mas estava sempre desatualizada. Então alguém entrou e tornou isso tão específico que qualquer um, mesmo com conhecimento limitado de Drupal, poderia fazê-lo, então todas as pessoas drupal na loja odiaram, então tiramos isso, e então não pudemos treinar ninguém novo e apenas os desenvolvedores do Drupal poderiam acompanhá-lo, então começamos a codificá-lo em Drush

Drush significa que qualquer um com experiência em Drupal poderia rodar algumas linhas de código e tudo iria “acontecer” magicamente. Não há mais "erro humano", é uma lista de verificação, mas em vez de um humano confuso tentando seguir uma lista de verificação, um computador a seguiu.

O problema era que mesmo a mudança mais simples precisava de um desenvolvedor e todas as mudanças tinham que ser testadas e, assim, elas desmoronavam rapidamente.

Eventualmente nos deparamos com a solução óbvia, que é algo embutido no Drush, o que dificultou muito a mudança.

Agora nós simplesmente temos um site chamado “clone me” ou algo parecido e sempre que temos um novo cliente nós apenas o duplicamos. Mudá-lo costumava envolver um programador e muitos outros trabalhos, agora qualquer um com a senha da nossa equipe pode mudar alguma coisa. Se um designer quiser dados de teste diferentes, ele será alterado e será automaticamente em nosso próximo projeto. Se um PM decidir que precisamos de outro usuário padrão para fins de treinamento, ele criará um e estará em nosso próximo projeto.

Nós tivemos a sorte de ter Gavin aqui no Gravity Switch por alguns anos. Ele contribuiu bastante com nossa cultura e nosso código, mas a sua sabedoria sobre quando “hackear” as coisas e quando processuralizá-las é algo que realmente mudou a forma como abordo a documentação.

Gavin nos ensinou que um bom código é auto-documentado.

Os 10 mandamentos da documentação

1. Você não deve documentar em excesso - Se demorar mais para documentar do que para fazer, você está documentando em excesso.
2. Tu automatizarás antes do documento - Retire o fator humano sempre que possível.
3. Você não deve atrapalhar a mesma coisa três vezes - se você estragou tudo ou teve que descobrir a mesma coisa duas vezes, é hora de proceduralizar.
4. Se ele falhar, faça com que ele falhe grande - as coisas mais difíceis são as coisas que você sente falta da primeira (e até da décima) vez que você as revisa. Se você tiver uma escolha entre criar um processo que interrompa a linha de montagem ou travar seu site se ele falhar ou criar um pequeno erro, sempre escolha “derrubar o site” porque pelo menos você identificará o problema pela primeira vez .
5. Você deve colocar o processo onde deve tropeçar - porque precisa ser encontrado.
6. Próprio - Ao seguir um processo, tenha em mente que seu trabalho é produzir o melhor resultado. Não é para seguir o processo. Sempre abordá-lo com ceticismo e analisar criticamente os resultados.
7. Admita quando não está funcionando - Às vezes as coisas podem parecer as mesmas, mas não são. Em nosso mundo, sempre precisamos de dados de teste padrão, mas o processo para criar isso no WordPress é completamente diferente de criá-lo no Drupal, então precisamos de processos completamente diferentes.
8. Corrigi-lo rapidamente - Se o seu processo estiver desatualizado, não ignore o problema e assine-o ou escolha as partes que deseja seguir. Corrigi-lo como você vai Isso levará apenas alguns minutos a mais na maioria dos casos, e esses minutos serão convertidos em horas na próxima vez em que você ou outra pessoa usar o processo.
9. Escolha suas batalhas - Steve Krug (o mestre da usabilidade) diz que você deve testar com frequência. Encontre o seu maior problema. Faça o mínimo de trabalho possível para que não seja mais seu maior problema e repita. Você não está tentando desviar do sistema, você está tentando fazer com que o sistema TODOS funcione melhor.
10. Revisitar - Se você já usou um processo uma dúzia de vezes e não o mudou, você deve pensar em como torná-lo mais eficiente ou se deve automatizá-lo.

• ← Como projetar para dispositivos móveis, quando você não tem um
• Como otimizar a página inicial do seu site para celular →