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.

1º Modelo - Modelo leve para download (apenas a estrutura de diretórios)

2º Modelo - exemplo para download (esse contem uns exemplos)

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/