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
  • http://www.pinceladasdaweb.com.br Pedro Rogério

    Ultimamente não estou utilizando de nenhum artifício para documentar meus projetos, não é má vontade não, é que falta saco pra isso mesmo, mas preciso começar a utilizar alguma coisa. Ótimas dicas!!!

  • luileslie

    Oi Henrique,

    Como sou Arquiteta de Informação, costumo trabalhar em projetos com algum tipo de documentação, mas acho mais interessante pensarmos em termo de etapas do processo e ferramentas disponíveis.

    De modo geral, podemos dividir a elaboração de um produto em 4 etapas: definição de uma estratégia, pesquisa, design e construção. Para cada uma dessas etapas existem muitas ferramentas disponíveis, e cabe ao profissional saber escolher aquelas que são relevantes ao seu problema.

    De qualquer forma, posso ressaltar dois documentos que considero muito importantes e que acabam sendo usados de uma forma ou de outra em quase todos os projetos: diagramas de telas e wireframes.

  • Felipe

    adorei teu post Henrique

    ficou mto bom mesmo. assim que eu tiver um tempinho vou responder com um post no meu blog sobre isso.

    afinal documentação eh trabalhoso, chato, desgastante, mas vamos confessar. faz mta diferenca. ainda mais se tu for ter que dar manutenção no site/sistema alguns meses depois de ter entregue o produto.

    abraços

  • Anderson Lobo Feitos

    Eu preferi responder com um post no meu blog. A resposta juntamente com algumas informações adicionais do processo de desenvolvimento utilizado estão neste link: .

    Espero ter ajudado.

  • Lucas Castro

    A empresa onde eu trabalho presta consultorias em TI. Não desenvolvemos nada para vender. O que ocorre, é que alguns funcionários como eu, acumulam cargos e acabam por desenvolver sistemas para uso restrito dentro da empresa.

    Geralmente faço um rascunho, algo parecido com um D.F.D. de Contexto para dividir o sistema em módulos e monto um cronograma de desenvolvimento.

    Os supervisores acompanham o desenvolvimento através de ferramentas colaborativas dentro da empresa, como um software de gestão de indicadores chamado Digital Cockpit, desenvolvido pela Solver.

    Os códigos são bem comentados, mas como até agora foram feitos apenas sistemas simples, nenhuma documentação em específica foi criada.

    Agora que está ocorrendo a integração dos sistemas em um grande portal, surgiu a necessidade de documentação e estamos correndo para criar um wiki. O maior tempo investido na documentação será no banco de dados.

  • Ricardo

    Hoje em dia a única documentação que utilizo e comentar bem detalhadamente cada classe e método do meu projeto, explicando os parametros, variáveis, retorno, pra que serve e a lógica de cada um.

    Isto porque hoje trabalho sozinho, mas quando trabalhava em equipe (ano passado) a utilização de wireframes, diagrama de classes e etc. era extremamente utilizado. E nos ajudava de forma muito positiva para o andamento dos projetos.

  • Rodrigo Fante

    AS unicas vezes que documentei algo foi na faculdade, todo tipo de diagrama possivel eu ja fiz, mas na vida real, nao sobra tempo infelizmente para isso.

  • João Jos&eacu

    Bem,

    Tenho trabalhado com projetos Web na Empresa Júnior do meu curso (C. Computacao), e estamos utilizando um modelo de processo que vem nos trazendo beneficios.

    Nosso primeiro passo para o desenvolvimento é uma pequena/suficiente analise de requisitos, que é feita até o ponto em que conseguimos elaborar telas (desenhos, prototipos html, design de photoshop, qualquer coisa rapida e facil) doque o cliente necessita.

    Fazemos isso para que o cliente possa perceber oque ele quer, através de algo visivel (nada de descrições gigantes e diagramas que soh analistas sabem pra que servem). No inicio, não trabalhamos muito com a documentação pois entendemos que o cliente será nossa principal fonte de requisitos (geralmente estar 'errada', mas se mostrarmos sempre oq ele esta decidindo, temos a tendencia de diminuir esses erros).

    Trabalhamos com a prototipação ate o ponto onde podemos colocar o site no ar, agregando valor ao cliente, mesmo que não exista nenhum sistema dinamico por traz do site. Fazemos na expectativa de obter o maior retorno possivel, dos clientes e dos usuarios que usarão o site (logico que tem casos que necessita de um sistema dinamico para que seja algo que traga valor).

    Depois, numa clara imitação do Beta Infinito do Google, vamos fazendo o suporte (sistemas dinamicos) do site com o tempo, e sempre que damos um pequeno passo concreto, aproveitamos para documentar (na medida necessaria) nossos projetos. Isso nos livra de um retrabalho muito mais custoso doque erros de planejamentos, o retrabalho da documentação. Documentando eu não ajudo meu cliente, ele não pode ver acontecer, ele nao pode decidir se ele realmente esta certo. Prefirimos dar a opção da mudança (mudanca de planos) aos nossos clientes do que gastar o tempo e dinheiro dele fazendo documentos que facilmente entram de desuso e desatualização.

    E de forma iterativa vamos completado o projeto.

    Mas comentando o post, concordo que cada abordagem é valida para seu contexto. Para nós tem funcionado de maneira satisfatoria (logico que temos outros problemas, que não é a documentação, que fazem atrasarmos nossos projetos).

    Só um PS. Somos 100% inspirados pela metodologia XP (eXtreme Programming)

    Parabens pelo post.

  • http://www.richardbarros.com.br/blog/ Richard Barros

    Olá! Dificilmente documento, mas sempre que vejo a necessidade de comentar e esclarecer algum detalhe em arquivos que serão compartilhados, não hesito.

  • http://www.dotes.com.br Luiz Júnior F

    Bom, com relação a documentação, na Agência Dotes (onde sou diretor de projetos e desenvolvimento), trabalhamos da seguinte forma: Se o projeto é pequeno, só construimos um mapa do site, em VISIO mesmo, o que agiliza e facilita bastante o trabalho. Depois disso prototipamos tudo primeiro em papel para depois o designer desenvolver as principais telas (Wireframes) com o auxílio de softwares gráficos (PS, CDR). Depois disso começamos a desenvolver o visual e tudo vai acontecendo. Para projetos mais estruturados e com uma estrutura maior, utilizamos de modelagem de dados, ou seja, fazemos tudo que é feito nos pequenos, só que com análise. Primeiro de tudo é desenhado o modelo do banco de dados (DER) e uma relação de requisitos, gostamos também de desenhar alguns dos documentos da análise estruturada moderna, tais como o DFD0, layouts de relatórios e etc…, também são feitos os diagramas de classes, o que ajuda muito na construção das classes e persistências, mas sempre, sempre analisamos cada caso individualmente. Cada caso é um caso.

  • http://www.quebarato.com.br Fred“

    Utilizamos o dotproject para documentar tudo do projeto, incluindo o sistema de tickets para sinalizar bugs a serem corrigidos. Também utilizamos um wiki que faz sincronismo com o subversion para termos documentado os arquivos do site, propriamente ditos e também, claro, documentar cada funcionalidade do site.

  • capixaba

    Wiki! Usamos o WikiDot para documentar qualquer projeto. Não tem coisa melhor. Aconcelho a todo mundo, em algum projeto mais extenso e que precise de documentação, a usar algum wiki.

  • Pingback: Você utiliza algum tipo de documentação em seus projetos para web? « [REF]()