sexta-feira, 13 de abril de 2012

Modelo de Documentação de Software

Já que eu andei falando muito de engenharia de software nada melhor do que montar um artigo que explicasse de uma vez por todas a diferença entre DOCUMENTAÇÃO DE SOFTWARE e UML e ainda liberasse um modelinho de documentação para download (atenção amigos, esse modelo é generico, o ideal seria vc adapta-lo para melhor atender o seu projeto. Mas acho que ele te da um bom 'norte' de como fazer, como se fosse um framework para documentar [NOSSA! APELEI])...

A verdade é que uma das coisas mais comuns na TI é as pessoas misturarem as coisas, isso é muito comum principalmente nos países latino-americanos em que queremos fazer primeiro e aprender depois (não que eu seja exceção[estou me referindo a exclusão])...

E por conta disso distorcemos alguns paradigmas importantes para desenvolvimento de software...

Veja bem, a cada 10 empresas de TI quando falamos a palavra documentação 6 pensam em UML, 1 pensa em documentação completa do projeto de software e as outras 3 não sabem o que é isso.

Associar UML a documentação não é um pecado, mas é algo incompleto pois uma documentação de sistemas é muito mais que um diagrama de caso de uso ou um diagrama de classe... Esses na verdade são complementos para uma boa documentação visto que eles foram criados em fase de modelagem do sistema e fazem parte sim da documentação do mesmo mas, sozinhos são uma penca de diagramas "sem sentido"... Ou você acha que é só fazer diagramas e pronto modelou e documentou?

Ta ta se vc for um gerente de projeto, analista de sistemas ou conhecedor de projetos de software talvez esteja se perguntando "ta, mas me explica o que é uma maldita documentação", e eu respondo; "uma documentação é uma documentação, ha! =)" e ai vc se atrapalha muito mais... e esse é meu objetivo... te atrapalhar para te mostrar o verdadeiro 'caminho das pedras'...


Vamos levar ao pé da letra... Eu sou uma pessoa(pelo menos no papel) e quando alguém pede minhas documentações o que eu faço? RG, CPF, Titulo de eleitor e etc... ou seja, tudo que me identifica como eu em texto/figura etc... com o software também é assim, imagine um sistema como um todo;
            Modelagem de dados, Regra de negócio, manuais do usuario, documentos de trabalho, commits, diagramas, comentários, código, mer...

No processo de desenvolvimento indiretamente vamos montando documentos do software criado (formalmente ou informalmente) e todos eles levam SIM a característica de documentação... então a questão não é exatamente o que é documentação mas sim "o que devo selecionar como documentação?". E é ai que começamos a parte funcional da coisa...


Por que precisamos de uma documentação? Qual o seu uso?

Meio de comunicação entre os membros de  um grupo de desenvolvimento;
Informações para as pessoas que venham a  fazer manutenção no sistema;
Informações à gerência de modo a ajudar a  planejar, fazer o orçamento e o cronograma;
Informações para ensinar aos usuários como  utilizar e administrar o sistema

E quais são os tipos de documentação?
De forma geral são 2, do processo e do produto.

  • Documentação do processo 
    É produzida para que o processo de desenvolvimento do software seja administrável . Registram os processos de desenvolvimento e manutenção do software .
  • Documentação do produto  
    Descreve o software que está sendo desenvolvido. É muito utilizada depois que o sistema é implementado, mas é essencial também para a  administração do processo de desenvolvimento.



Existe ainda uma explicação muito detalhada desses dois tipos de documentação mas acho que isso é o bastante para vc que esta com pressa e precisa do modelo.

Estou colocando aqui para download um modelo de documentação.











ATENÇÃO PESSOAL! EU ANDEI RECEBENDO UNS E-MAILS DIZENDO QUE O MODELO DE DOCUMENTAÇÃO ESTAVA VAZIO, QUE SÓ TINHAM PASTAS.... A PROPOSTA INICIAL É JUSTAMENTE ESSA, APENAS MONTAR A ESTRUTURA DE DIRETÓRIO... MAS JÁ QUE O PESSOAL PEDIU EU MONTEI UM SEGUNDO MODELO PARA FACILITAR O ENTENDIMENTO.




Referências importantes

The UML is Not Sufficient (Scott Ambler)
http://www.agilemodeling.com/essays/realisticUML.htm

Muitos e muitos artigos do Martin Fowler
http://martinfowler.com/

30 comentários:

  1. Parabéns me ajudou muito esse modelo!

    ResponderExcluir
  2. Palmas é a unica coisa que me resta...


    Arregaçou no artigo!

    ResponderExcluir
  3. A maioria dos arquivos está com defeito, e simplesmente não abre. Lamentável!!

    ResponderExcluir
  4. Excelente, só me resta dar os parabéns!!!!!

    ResponderExcluir
  5. Paulo show de bola cara muito bom mesmo, mas como eu defino o que é realmente importante para registrar em documentação? Fico com dúvidas nesse caso pois sou programador e a minha empresa esta pedindo a maldita documentação do projeto que trabalhei e ai o que eu faço? O certo não seria eu documentar mas sim os inúteis dos Gerentes de Projeto.... Obrigado denovo seu modelo esta me ajudando só fica a dúvida se por exemplo posso colocar a lista dos commits como documentação.

    ResponderExcluir
    Respostas
    1. Caro Jonathan, acho que principalmente uma descrição técnica e alguns diagramas de classes são necessários. Como eu disse isso depende muito daquilo que se espera da documentação. Eu acredito que os commits na maioria das empresas não é necessário.

      Excluir
  6. Olá, gostaria de saber qual é o melhor programa gratuito para fazer a documentação de um software e exportá-la em PDF e HTML.

    ResponderExcluir
  7. Muito obrigado ! Será de grande valia.

    ResponderExcluir
  8. Olá, tudo bem? gostaria de saber se você tem algum material específico de documentação de software para usuário final?

    Atenciosamente,

    Lidiane

    ResponderExcluir
    Respostas
    1. Olá Lidiane,
      Você conseguiu algum material para usuário final? Também procuro sobre isso e não encontro nada.

      Excluir
    2. Vou verificar se encontro algo mais simples e ai atualizo o artigo.

      Excluir
  9. Olá!
    Alguém sabe de referências sobre documentação de software para usuário final?

    Tks!

    ResponderExcluir
  10. Este comentário foi removido pelo autor.

    ResponderExcluir
  11. os links estao quebrados brow...ok?
    obrigado

    ResponderExcluir
  12. os links estao quebrados brow...ok?
    obrigado

    ResponderExcluir
  13. não foi permitido fazer nenhum dos dois downloads, poderias enviar para o meu email? danielli.mesquita@gmail.com

    ResponderExcluir
  14. não foi permitido fazer nenhum dos dois downloads, poderias enviar para o meu email? danielli.mesquita@gmail.com

    ResponderExcluir
  15. Pode enviar por email?
    danydovale@hotmail.com

    ResponderExcluir
  16. poderia me enviar por email nao consegui realizar o download
    well.moreira@live.com

    ResponderExcluir
  17. Este comentário foi removido pelo autor.

    ResponderExcluir
  18. não foi permitido fazer nenhum dos dois downloads, poderia enviar para o meu email? cvscaminha@hotmail.com

    ResponderExcluir
  19. Muito bom seu artigo! Mas não me foi permitido fazer nenhum dos dois downloads. Se puder me enviar por e-mail, agradeço: cantuario2@hotmail.com

    ResponderExcluir
  20. Para realizar o download, basta adicionar o ".br" após "soulgothic.com".

    Espero ter ajudado.

    ResponderExcluir