Acredite, documentação é muito mais que as tais histórias

Acredito muito além das sábias palavras do Neil Ford, keynote no Agile Brazil de 2012, pois temos dois tipos de usuários em cada projeto, aquele óbvio, que utilizará e se beneficiará do produto entregue, mas também há um usuário oculto, aquele que dará manutenção, sustentabilidade, continuidade no que construímos, podendo até ser (feliz ou infelizmente) nós mesmos.

Como Agile Coach, consultor ou professor, insisto na necessidade de distinguir o romantismo de muitos livros e artigos de agilistas da realidade ou momentuum de sua empresa, área, equipe, tecnologia. Enquanto evoluímos no quesito de excelência em engenharia de software, devemos ter clareza do custo x benefício relativo a aceleração e redução do processo e custo de sustentação.

A tempo, a solução não é aquela encontrada pela maioria absoluta das empresa, que mascaram a sua ineficiência e péssimas práticas de desenvolvimento voltadas ao imediatismo da entrega a qualquer custo. Gerar uma alta OPEX recorrente para ter uma CAPEX reduzida amplia uma percepção equivocada de ROI, mas é fogo amigo, equivocado e inaceitável.

CAPEX (expenditure) ~ despesas ou investimentos em bens de capital; despesas de capital; aquisições. OPEX (operational expenditure) refere-se às despesas operacionais, recorrentes, continuadas.

Tenho uma extensão à Teoria da Agência, ou você está trabalhando para ficar amadoramente bem na foto e ser promovido ou tem a responsabilidade e transparência de um profissional? A entrega de hoje está gerando mais um legado a ser mantido com doses maciças de custos recorrentes ou tem baixo custo de operação por ter sido corretamente construído e documentado?

O volume reduz-se conforme a evolução de sua excelência em engenharia de software, você segue DDD, componentiza, usa BDD, especifica e automatiza por exemplos, constrói código limpo, segue boas práticas de desenvolvimento na sua arquitetura e plataforma, automação de testes e integração contínua.

Aos poucos a documentação vai se integrando ao ambiente, projeto e produto, mas não é mágico, não só porque sempre teremos registros importantes a fazer, mas porque muitos leem em um artigo que documentação é do mal e sem ter o menor critério ou escrúpulos, passam a defender um go horse documental e tem a desfaçatez de citar grandes nomes que relatam projetos de excelência …

1. Pré-game

Acredito no valor da existência de conceitos como Funil de ideias, Gestão de portfólio, programas e projetos, comitês gestores. Grandes empresas não podem prescindir disso, tanto quanto contam com os préstimos de uma governança corporativa, governança de TI, PMO, gerentes de projetos ou papel preocupado na transversalidade, em aquisições, alocações, indicadores gerenciais.

Todo o tempo e processo existente antes do projeto iniciar sua etapa de execução ou desenvolvimento é conhecido como pré-game, ideias, discussões, submissões, descartes e aprovações, culminando no planejamento que habilita a fase seguinte de game, composta por sprints, especificação, desenvolvimento, validação e entregas. Eu posso oferecer um mix flexível, mas consistente de planejamento:

1.1. Project Model Canvas Eu utilizo para a explicitação das informações básicas coletadas, um Termo de Abertura visual em uma folha grande e postits contendo o porque o projeto é necessário, o que ele é em sua essência, quem se envolverá e percepções sobre como será planejado, quando e quanto custará. Chamo a atenção para premissas, riscos, restrições e expectativas;

1.2. Elevator Statement Um ótimo aquecimento, uma abstrair e entender justificativa, quem são os clientes, qual o desafio, problema ou oportunidade, que tipo de solução imaginamos, qual o valor de negócio esperado, o que é utilizado hoje para atender esta necessidade e quais os diferenciais para que o cliente e usuário deixe a solução atual e apoie e use a nova;

1.3. Personas Quem são os atores envolvidos, seus perfis, necessidades e objetivos. Caso a caso, de 0 a 100, posso apenas caracterizá-los até utilizar de Value Proposition Canvas para identificar seus interesses, dores e expectativas de ganhos. Uma técnica dedicada a gerar empatia, tentar ver pelos olhos de cada parte envolvida, antecipando percepções de ganhos e perdas;

1.4. Customer Journey Map Uso variações simplificadas desta técnica de mapeamento, convergente a uma User Story Mapping, para entendermos os fluxos de atividades necessárias para as principais jornadas dos usuários da solução em estudo. Cada jornada, passos manuais ou informatizados. Queremos entender o passo-a-passo das personas, identificar funcionalidades do produto;

1.5. Scrum SetUp Canvas Artefato proposto para explicitar entendimento, combinações sobre tecnologia e metodologia, necessidades prévias/recorrentes a serem consideradas para efeito de modelagem, planejamento, execução ou entrega. Qual a composição de equipe, mapeamento de tecnologia, boas práticas necessárias, métricas, DoR e DoD, atividades e reservas para start e velocidade;

1.6. Release Plan É a combinação de diferentes técnicas para o planejamento, usando técnicas de estimativa e capacidade baseadas em valor e cronologia. Ao final teremos metas iniciais para cada sprint em relação a construção do produto. Conceitos como Minimo Produto Viável, histórias do usuário e histórias técnicas, culminando com o product backlog, uma lista priorizada e planejada;

2. Game | Sprints | Construção

A construção de software gera produtos e soluções que se perpetuam por muitos anos, décadas, conheço soluções construídas nas décadas de 80 e 90 que ainda hoje sustentam negócios complexos e críticos com sucesso. A maioria delas possui uma documentação excessiva e abrangente, defasada e inevitavelmente comprometida, a psicologia explica, frente a centenas de páginas a maioria acaba rolando e enrolando e fugindo de se atolar e dedicar dias da semana só a isso.

O segredo não é se amotinar, dizer que documentação é do mal, que ela é inútil, porque inútil é o exagero, redundância, complexidade, dificuldade. Como tudo na vida, o equilíbrio é o ideal e em agilidade as retrospectivas precisam fazer seu trabalho, identificar desperdícios e gargalos (Lean), gerar atitude, proposição de melhorias, sempre baseado em fatos e não em paixões e idealizações.

2.1. Para o DoR (Definition Of Ready):

Importante, o registro documental do nosso DoR é rico demais para não receber alguma atenção, talvez um grupo de trabalho que defina o que, como e onde. A documentação de funcionalidades deve ter esta orientação, uma árvore racional que permita rapidamente localizá-la, a orientação para sprints é temporária, a orientação funcional é permanente e deve deter informações cumulativas úteis.

2.1.1. User Stories – Narrativa e critérios de aceite, incentivando o uso de notações. Como <quem><o que><porque> para a narrativa e <dado que><quando><então> para critérios, que representarão de forma atômica diferentes regras, como as de negócio e integração. Uma linha para cada, ao invés de parágrafos embaralhados com várias regras, preferencialmente seguindo BDD.

user stories - sebastien frechina

2.1.2. Protótipos com explicações – Via de regra, na absoluta maioria dos projetos de que participo, materializando a necessidade, exponenciando o papel de um bom UX (user experience), a oportunidade de termos o desenho das telas com diferentes características de navegação e usabilidade, enxuta, simples e objetiva, que norteará de forma efetiva o desenvolvimento melhor possível;

2.1.3. Documento complementar – Diferentes empresas chamam de diferentes nomes, mas é um documento que explicita questões desde regras de integração, SEO, funcionais, alertas ou lembretes que registram questões intrínsecas que poderão gerar problemas futuros se não forem registradas. A regra é bem simples, escreva somente o que precisa escrever, o melhor documento é aquele curto, que explica o que se desconhece, evite explicar o óbvio e já acordado, conhecido (*);

(*) há quem coloque estas informações e regras complementares no mesmo documento da User Story, inclusive o protótipo, e sai por ai dizendo que só usa a User Story e é suficiente … mas só porque está tudo junto não quer dizer que é uma coisa só.

2.1.4. Cenário(s) de testes – Para mim, e é assim que conduzo em todas as empresas por onde passo, a construção pelo menos do cenário principal de testes é essencial. Este cenário fazer parte do DoR é um importante insumo para os desenvolvedores, que os revisarão antes de liberarem a funcionalidade para testes e homologação. Para o DoR eu recomendo garantir o cenário principal, o SQA ou tester pode trabalhar ou não depois os cenários alternativos a seguir;

2.2. Para DoD (Definition Of Done):

2.2.1. Código auto-explicado – Seguir boas práticas de engenharia de software, potencializada por conceitos básicos de aprimoramento do código gerado como paterns, pair programming, code review em suas diferentes formas. O código gerado por equipes ágeis e conscientes de tudo o que falei acima, esforçam-se para gerar código limpo, legível, componentizado, boa OOP;

2.2.2. Testes automatizados – O uso de boas práticas como BDD com o uso de ferramentas para geração de testes, TDD ou pelo menos testes unitários, testes funcionais. Todas estas boas práticas geram informações e conhecimento rastreável e seguro, vivo, que se mantém atualizado sempre. Bem feitos são um manual dinãmico e explicativo orientado a comportamento e engenharia;

2.2.3. Versionamento e integração contínua – A ideia é seguir uma boa arquitetura e engenharia de software, de forma que crie uma matriz e árvore passível facilmente de ser conhecida a partir de sua navegação. O uso de boas ferramentas integradas geram baixo custo de assimilação, facilita troca de responsáveis, acelera novos integrantes, pesquisas e mesmo refatoração;

2.2.4. Gestão de configuração – É uma prerrogativa inalienável a qualquer equipe, na minha opinião quaisquer scripts ou ações relacionadas a promoção daquilo que está sendo feito carece registro, aglutinação e versionamento. Algumas empresas de diferentes tamanhos deixa esta atribuição a tarefas manuais e pessoais, um erro que gera riscos e impede agilidade em ocorrências;

2.2.5. Métricas, indicadores e Status Report – O uso de boas práticas em métricas também envolvem métricas técnicas e indicadores, que devem ser escolhidos com cuidado, como as taxas de cobertura citadas acima, mas também de softwares responsáveis pelos builds e integração contínua, SONAR, a maioria são automatizadas a partir de scripts e mapas apresentados nas Sprints Review, acompanhando entregas e seus status report.

Cada um dos itens acima em teoria foram construídos dentro do próprio processo e mantidos atualizados, após o projeto encerrado é preciso mantê-los vivos, o que demanda mínimo esforço, quer em uma ferramenta ALM robusta, sharepoint, confluence, na dúvida se isso é possível, me manda uma msg …

Manual – Amaldiçoado por muitos, mas ainda úteis em casos específicos como software de prateleira, quer manuais físicos ou virtuais, conforme negócio. As vezes na forma de uma apresentação para replicação de treinamentos, as vezes vídeos, esporadicamente manuais em pdf, seguidamente virtuais, acessíveis durante a navegação, sensíveis a contexto. Pelo menos um FAQuizinho rola.

Um comentário sobre “Acredite, documentação é muito mais que as tais histórias

  1. Pingback: Ao invés de perguntar sobre documentação, aprenda com ela | Jorge Horácio "Kotick" Audy

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s