News & Events
Tempo x Documentação, quem vence a briga?
Primeiro gostaria de fazer alguns questionamentos:
Você faz documentação de seu software?
Faz o levantamento de requisitos?
Escreve no papel tudo aquilo que vai ser preciso para desenvolver o projeto?
Se a resposta as perguntas acima é NÃO. Lhe faço uma nova pergunta: Por quê?
Deixe-me advinhar: falta tempo?
Muito bem, essa é a questão de hoje: Tempo versus Documentação. Gostaria de contar minha experiência para que vocês possam também refletir sobre o tema.
Iniciei como desenvolvedor já há algum tempo e comecei em empresas que não tinham o hábito de fazer o levantamento de requisitos, análise, planejamento do sistema etc antes dele ser concebido. A maior questão de todas era sempre a mesma: falta de tempo. Muitos desenvolvedores, principalmente os autônomos, vão concordar comigo numa questão. Se você tiver que parar e fazer a documentação e/ou levantamento de requisitos, seu cliente compra de outro. Sempre me esbarrei nessa questão. Era sempre muito difícil sentar na frente do Word e elaborar os textos para então desenvolver o sistema.
Fiz um curso há cerca de 4 anos sobre Orientação a Objetos e no curso estava incluso um mini-curso de documentação. Maravilhoso, muito legal poder escrever no papel tudo que o sistema poderá fazer, todas as tabelas do banco de dados, a modelagem UML, etc e tal. Mas confesso que pensava: Isso é para empresa grande, com muitos programadores, desenvolvedores, analistas, suporte, etc. Não consigo fazer isso. Não tenho tempo.
Muito bem, trabalhei em duas empresas nos últimos 4 anos que não eram tão grandes assim e que exigiam que o desenvolvedor fizesse o levantamento de requisitos. A partir daí minha mente começou a se abrir. Cheguei a conclusão que a questão tempo é bem relativa e se você “não perder” um pouco agora, ele vai se multiplicar no momento em que o desenvolvimento iniciar.
Em outras palavras quero dizer que a importância de uma documentação e validação por parte de outros membros da equipe é muito maior do que se pode imaginar. O fato é que, escrever é chato, muito chato, mas desenvolver sem saber ao certo qual o rumo do seu software/website é pior ainda.
Participei do desenvolvimento de uma aplicação relativamente grande recentemente onde uma das minhas principais tarefas era justamente fazer o levantamento dos requisitos e validar com o cliente e meus superiores. O projeto estava previsto para finalizar em 15 dias, contando 5 para redação da documentação. Erramos no prazo. Foram ao todo 30 dias, sendo os mesmos 5 para documentar e o restante para desenvolvimento, testes e ajustes finais.
Durante o processo de desenvolvimento, encontramos vários detalhes que passaram desapercebidos durante a concepção. Esses detalhes foram revistos e ajustados. O produto final ficou excelente, modéstia parte. A lição que aprendemos, minha equipe e eu, é que se não tivéssemos feito a especificação, levantamentos, etc, teria sido muito pior.
Se me perguntam hoje se faço documentação, sim faço. E forço sempre a barra para que meus técnicos, analista escrevam antes o que será desenvolvido. Sentamos, fazemos reuniões, ajustamos o documento, refazemos as analises, reunimos de novo e vamos para o desenvolvimento.
Falando comercialmente: é mais barato você parar algumas horas técnicas para fazer as devidas documentações e reuniões, do que depois ter que refazer o projeto ou mesmo corrigir regras de negócios.
Controles e Modelos
Com certeza a medida que a empresa vai crescendo e novos projetos vão sendo desenvolvidos, a quantidade de arquivos Word, PDF, etc e desenvolvedores vai aumentando. Controlar tudo isso não é fácil, por isso é recomendável usar uma ferramenta para controle dos arquivos e modelos.
Onde trabalho usamos o Borland StarTeam que, além de guardar os arquivos, controla a versão deles.
Em relação a modelos: existem milhares na internet ou o desenvolvedor/analista pode criar seu próprio modelo de documento. Abaixo você encontra três arquivos que estou disponibilizado para que tenham uma idéia de como trabalhamos.
É claro que os dados são fictícios, mas já expressam como funciona o processo.
http://www.adrianosantos.pro.br/pub/timexdoc.rar
Um forte abraço a todos e até a próxima.
Adriano Santos
http://www.twitter.com/delphi2delphi
http://www.twitter.com/asrsantos
Siga @tdevrocks no Twitter agora e fique por dentro de todas as atualizações do blog.
Siga também o autor @asrsantos
Muito bom mesmo Adriano,
Eu sempre pensei que fosse muito trabalhoso e até desnecessário fazer toda essa papelada, em vista do tamanho dos softwares que eu desenvolvo. São soluções muito simples, para problemas simples.
Mas, vendo por esse lado, eu me convenço cada vez mais, de que, mesmo sendo um sistema simples, é muito bom preparar toda a documentação, até mesmo para definir prioridades, já que eu tenho uma mania persistente de encher o sistema de gadgets, e outras funcionalidades, que no final, são realmente muito úteis para os meus clientes, mais que acabam se tornando um caos na hora da organização & manutenção.
Esse post foi muito esclarecedor, abriu novos pontos de vista para mim, parabéns
Geovani de Souza Scossabia
Atire a primeira pedra quem nunca disse ou pensou “Para que perder tempo em documentar o projeto?”.
I´m guilty.
Pois é, concordo com nosso amigo Adriano, não importa o tamanho e nem em que linguagem o projeto será desenvolvido, a documentação sempre será necessária.
Várias são as técnicas, ferramentas e modelos de documentação, o ideal é trabalhar com aquela que melhor esteja adaptado às suas condições e manias(rsrs)
Acredite, uma hora ou outra será necessária recorrer à documentação.
Há aqueles que “se garantem”, bem, para esses deixo que o tempo possa provar o contrário.
Ótimo feriado a todos.
Edson S. dos Santos
http://twitter.com/edsonssantos
Falta de tempo nunca é o motivo real.
Leia-se ai: administração ruim do tempo.
Nas missões apolo tinha um item do treinamento para uma determinada situacao de risco.
Caso aquele acidente viesse a ocorrer, os astronautas teriam somente 5 minutos de ar pra resolver.
eram treinados pra parar e conversar sobre o que fariam durante 4 minutos e só iniciar a ação no último minuto.
Pois se no meio da ação vissem q era o caminho errado poderiam nao ter uma segunda chance.
Justamente por faltar tempo é que deveriamos planejar e documentar.
Pois nao seria legal chegar no final do prazo, ou no dia da implantacao, e descobrir que algo nao está a contento
Sempre penso nisto no meu trabalho. Nunca vou direto ao codigo.
Sempre faço uma lista de desejos, uma lista de nomes de classes e de metodos
rabisco alguns UMLs e dai sigo alternando entre criaçao e atualizacao da documentação
Acabei achando um meio termo entre documentacao perfeita e codificacao acirrada.
Faço a documentaçao convencional para o q tiver de excessao, algo fora do padrao do resto do sistema.
E a principal documentacao é feita pelos meus identificadores.
Nomes como TFormaPagItem, TFormaPagList, procedure TFormaPagList.ImprimirFiscal, FPagIndiceAtual:integer, ja dizem muito sobre para que servem.
Gosto de fazer o código falar por si mesmo.
O mesmo para a estrutura do banco de dados.
O nome dos campos e das tabelas tem q deixar bem claro para q servem e segirem padroes de nomenclatura
Uma coisa importante pra mim é o reaproveitamento de codigo. Como saber qual das minhas classes antigas se encaixa num projeto novo sem nao tiver uma documentaçao?
Ricardo Bianchin
Rio de Janeiro
Dor de cabeça! Chatice!
Essas duas palavras com certeza vêm à mente de qualquer programador que está iniciando sua jornada profissional quando a questão é documentação de projeto. Aliás, todo e qualquer processo em que se tem algum trabalho e não se tem um resultado positivo a curto prazo, acaba se tornando, superficialmente, uma chatice. Contudo, na prática, ao ganharmos experiência, percebemos sua importância. Não é a toa que é vasto o material sobre a documentção de sistemas nos meios de informação (livros, internet, faculdade, etc.)
Falando sobre a minha parte pessoal, desde que ingressei na profissão, sempre fui cobrado, de várias formas, para documentar o que eu estava fazendo e antes de tudo, me atentar ao que já estava documentado. Então, satisfatoriamente, acabei me habtuando a fazer tal processo, ou seja, virou uma rotina “boa” para mim.
Atualmente o que faço é exatamente o que foi me passado de início, que é cobrar os profissionais mais novos que ingressam aqui na empresa, para que a “documentação” faça parte da sua rotina.
Fabrício Hissao
Araçatuba-SP
Olá Adriano,
Concordo com você em gênero número e grau.
Documentar todo o processo de desenvolvimento de software não é Fácil. Só que mais dificíl ainda e fazer a manutenção em um sistema sem documentação.
Hoje muitos desenvolvedores não fazem a documentação dos seus sistemas e na hora de fazer a manutenção ficam perdidos em meio a tantos códigos. Existe tantas ferramentas disponíveis inclusive free muitas delas.
Abraço,
Edson Lidorio
Eu concordo plenamente com suas palavras, e aconteceu a mesma coisa comigo, a principio falava para que perder tempo documentando enquanto posso estar botando a mão na massa.
Pensava que era uma chatice, mas depois que começamos a documentar na empresa que eu trabalho, vi que na verdade em vez de perdermos tempo ganhamos, pois se perde um pouco no comeco mas ganha tempo lá na frente, principalmente se entrar um novato na equipe se não tiver nada documentado o coitado fica perdido.
Abraços.
Fernando Derkoski de Souza
http://www.twitter.com/brilvio
fernando@mundonerd.org
Com certeza todos esses comentários são altamente válidos. Sou desenvolvedor autônomo e desenvolvo sob medida para meus clientes o que acaba criando um vinculo bastante estreito de amizade entre os usuários e eu, principalmente na fase de levantamento de requisitos. Pois bem, tudo isso leva a um relacionamente profissional bastante duradouro, e, como tal, também os sistemas sempre deverão receber atualizações seja por força de lei seja por comodidade administrativa.
E se essas atualizações forem necessárias daqui a 5 anos? Como fazer para efetuá-las com segurança e mais rapidamente?. Como já amplamente explanado, a resposta está na documentação.
Antigamente não me preocupava com a documentação e partia logo para o código, agora ao precisar fazer as atualizações perco um tempo considerável para me situar na lógica dos sistemas.
Enfim documentação não é perda de tempo, principalmente se o cliente terá um relacionamento longo conosco.
A documentação de software veio a ter importância para mim da maneira mais cruel que se possa imaginar. Em suma, ela veio através de cobrança superior (diretor da empresa).
Como a maioria dos desenvolvedores, minha equipe de trabalho era muito eficaz na parte prática da programação em si. Estudávamos conceitos e novos métodos e, por “falta de tempo” desprezávamos a parte “teórica” do negócio, que podemos resumir em “documentação” do sistema que desenvolvíamos. O tempo foi passando e nunca precisamos, de verdade, da tal documentação, mesmo sendo orientados pela direção da empresa a fazê-la. Certo dia, com o sistema tomando novos rumos, durante uma reunião, foi nos cobrado o fluxo de tal rotina no nosso sistema “carro-chefe”. Após muitos “achismos”, nosso gerente aconselhou a gente a consultar a documentação para sanarmos as dúvidas e acabar a reunião. Foi aí que percebemos que além de não tê-la, perdemos um “bom” tempo estudando tanto o código fonte e o banco de dados, quanto o sistema rodando, para darmos uma resposta satisfatória à nossa direção.
Lição aprendida! Hoje, documentamos tudo ao passo que o sistema vai evoluindo, evitando assim, re-trabalhos e re-pensamentos.
Essa questão foi muito bem levantada pelo autor do blog.
Alice Lumiko
Parece aquela história, é mais fresquinho por que vende mais ou vende mais porque é mais fresquinho.
A documentação é importante, mas como foi dito, é que nem tudo é imutável, porque cliente não quer saber o que você entendeu ou o que foi especificado, ele quer um resultado e quanto menos ele tiver que pensar para obter este resultado melhor.
Incrível como cliente tem a capacidade de mudar de idéia e adicionar itens. Por isto normalmente os contratos são por hora e abertos, ou seja, fazemos o que ele quer e como ele quer, mas cobramos em horas. Isto permite que sejam mudados os requisitos, documentadas as mudanças e ainda cobrado por isto, que é um ponto crucial para nós desenvolvedores.
Oswaldo dos Santos Araujo
Artigo e comentários excelentes.
Mas agora estou enfrentando na empresa onde trabalho um desafio maior ainda, mas que juntamente com a dodumentação reduz drasticametne todo trabalho de refactoring da aplicação e quantidade de bugs do sistema. Trata-se do Desenvolvimento Orientado à Testes.
Logo depois do levantamente de requisitos, porém antes da efetiva implementação do código, são criadas as units de teste do sistema e só depois vem a codificação dos requisitos.
A cada funcionalidade desenvolvida, são realizados os testes da mesma e dessa maneira validadas todas as regras de negócio que vieram do levantamento de requisitos.
Tenho percebido nestes últimos tempos que um desenvolvimento eficaz passa por estes dois caminhos entrelaçados Documentar e Testar …
É inevitável deparar-se no mundo do desenvolvimento com a questão: Documentar ou Não Documentar?
Seu tópico é muito interessante, e abriu espaço para diversos desenvolvedores comentarem suas experiências.
No meu caso tenho 10 anos de desenvolvimento, e a 5 anos (quando criei minha empresa e decidi ser autônomo) comecei a documentar “de verdade” todos os meus softwares.
Hoje em dia tenho muita tranqüilidade pois o processo de documentação, além de fixar mais em sua mente como funciona seu programa, facilita muito a manutenção e reduz a quantidade de erros numa futura modificação ou implementação.
Documentar um software deve se tornar rotina diária de um desenvolvedor que deseja se tornar bem sucedido no mercado de trabalho.
E finalizando: sobre a questão tempo. Você pode até perder alguns clientes no início, mas futuramente o tempo “(não) perdido” será compensado pela qualidade superior do software que irá lançar no mercado.
Abraços
Aqui vai um exemplo de como trabalhamos com várias tecnologias.
Trabalho em uma empresa com um pouco mais de 200 desenvolvedores, temos sistemas em PHP, .Net, Java, Delphi e VB. Criamos um padrão visual utilizado em todas as tecnologias. Com isso, nosso usuário que utiliza mais de um sistema desenvolvido por nós se preocupa apenas com o negócio, pois para ele consultar, cadastrar e fazer emissão de relatórios é tudo igual, mesmo sendo cliente servidor ou web.
Também criamos um documento de padronização de código para cada tecnologia, o de delphi eu mesmo escrevi, e para quem tiver interesse, esta em: http://delphi2010.wordpress.com.
Para o versionamento de código fonte e documentação utilizamos o SVN.
E para documentação utilizamos RUP com algumas alterações para melhor nos atender. Para quem quer ou já utiliza RUP, segue material bem interessante http://www.wthreex.com/rup/portugues/index.htm
Agora considerando alguns comentários sobre tempo levado para criação dos documentos, etc… Aqui, nós tivemos um ganho muito grande na manutenção dos sistemas. Ficou extremamente fácil o entendimento do negócio de cada sistema, sem contar quando contratamos um novo funcionário, o mesmo consegue dar manutenção em nossos sistema com pouco tempo de casa.
Bem pessoal, é isso.
Everson Novka
Arquiteto SOA
enovka@10picos.com
http://delphi2010.wordpress.com
Ótimo post!
Pena que o arquivo com os modelos não está mais no ar e não encontro um material bom na internet 🙁