Você utiliza algum tipo de documentação em seus projetos para web?

Eu não faço a mínima idéia de quantos leitores que passam por aqui diariamente trabalham com algum tipo de documentação ou fluxograma nos projetos em que participam. Este texto é uma espécie de pesquisa para descobrir isso. Quais os tipo de documentação você lida e em que contextos?

Pessoalmente nos últimos tempos eu comecei a “arquitetar a informação” de um projeto de forma mais gráfica utilizando diagramas, em específico o diagrama de Garrett. Tenho participado também do processo de análise (mesmo não tendo formação em ciências da computação ou algo parecido) fazendo o levantamento de requisitos funcionais e não funcionais, descrevendo o que o sistema terá, fluxos de navegação e interação do usuário etc (posteriormente nos diagramas), em equipe, junto com o programador.

Neste meu recente contexto, apenas eu e o Flávio Kaminisse (o programador) somos a “equipe”. Mesmo que ambos tenhamos especialidades diferentes, os questionamentos mútuos contribuíram para dar soluções ao nosso “problema”. Juntos nós fizemos o levantamento destes requisitos, documentamos os campos do sistema e posteriormente ele sozinho, escreveu um documento de regras de negócios dentre outros específicos para que os futuros programadores que venham a trabalhar no projeto não se sintam perdidos. Mas o que eu percebi de vantagens nessa brincadeira, foi o quanto participar desse processo inicial em equipe foi fundamental ao evitar erros futuros, ao detalhar trechos complexos e requisitos não funcionais do sistema que teriam algum impacto no desenvolvimento.

Após todos estes detalhes da análise e de requisitos é que eu montei um diagrama com a interação do usuário e adicionei pequenos comentários nele, (construído no Visio ) em cada “página”, com os tipos de campos e detalhes que seriam úteis se algum outro designer chegar a colocar a mão no meio do processo de desenvolvimento. Coloquei alguns comentários também do tipo, “isto deve ser em formato de tela modal”, ou então “deve utilizar o script tal e usar máscara nos campos”, e assim por diante.

Existe o documento perfeito?

Concordo com Fahey ao dizer que não existe o santo graal da arquitetura da informação em termos de documentação. Não só na arquitetura mas em desenvolvimento de software ou análise ou o que for. Não existe um documento “perfeito”, o que existe são soluções perfeitas para contextos específicos, nem demasiadas e nem pobres. Em um site pequeno, com apenas um formulário de contato de “programação” não vale a pena perder tempo fazendo levantamento de requisitos, análise, etc etc etc… No máximo um documento de MindJet com o que cada página tem que ter de informação é mais que suficiente.

Quais os contextos?

Os contextos para documentação podem ser muitos e serem influenciados pela experiência e maturidade da própria equipe. Qual é o nível de detalhamento destes documentos? Alguém conhece o Getting Real já citado pelo Walmar? Há projetos em detalhes exagerados que chegam a se tornar fetiche para alguns, e para quem aplica o Getting Real em tudo pode faltar detalhes “teoricamente” de extrema importância.

Outro contexto do resultado final destes documentos é a especialidade de quem os cria e os objetivos finais. Um analista sem nenhuma experiência com programação terá uma visão de um documento de análise completamente diferente de um programador experiente que só agora está começando como analista. Um arquiteto da informação que não sabe a diferença em HTML e CSS (exagerando um pouco) vai gerar um diagrama de interação ou detalhamento diferente de um profissional que era (ou ainda é) web designer com muita experiência em programar no client side . Um documento de levantamento de requisitos tem objetivos completamente diferentes de um diagrama de interação do usuário, e assim por diante.

Acredito que o contexto e o bom senso do desenvolvedor é que vai guiar e levar um projeto ao sucesso, contemplando boa produtividade dos envolvidos, evitando surpresas eretrabalho durante o desenvolvimento, obtendo resultados elegantes, etc. “A documentação foi criada para o homem ou o homem foi criado para o documento?”, diria Jesus se fosse um gerente de projetos hoje! Mesmo que o ROI final não consiga mensurar certas coisas, os envolvidos no projeto vão saber no final o quão fácil de mexer no código de um projeto grande, o quão otimizado ele ficou, etc.

Por isso eu te pergunto: Como você documenta seus projetos? Quais os contextos em que isso ocorre? Quais as exceções? Usa alguma ferramenta específica? A quantidade de comentários neste texto vai revelar se apenas uma minoria trabalha com algum tipo de documento, ou então que essa minoria é ocupada demais para deixar um comentário aqui para iniciar um diálogo, ou então que eu escrevi um texto longo demais…! Se quiser contribuir escrevendo no seu próprio blog e não aqui nos comentários, sinta-se à vontade! Eu posso linkar você aqui neste texto! Não estou dando nenhuma pen drive para os melhores textos mas um link para o seu pagerank está garantido se você contribuir!

Mais…

  • Beduihno