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/

Formularios no zend framework

Vamos limpar nossa mente para a imaginação...

Como seria bom reaproveitar um formulario de forma que eu pudesse definir destinos diferentes ou ainda inserir um ou dois campos a mais... uma validação lógica e evitar scripts como SQL injection sem ter muito trabalho... deve ser um sonho... não sei...

Será que isso é possível? (Não vamos evangelizar o ZF mas...) Com o Zend Framework MUITA coisa é possível sem precisar "escovar bits"...e por isso hoje vou falar sobre Zend_Form ensinando a criar formularios completos sem muito trabalho e ainda reutilizando eles.

A verdade é que quando eu comecei a trabalhar com o ZF eu não gostava muito do Zend_Form e sempre achei melhor utilizar formularios escritos direto na view... Tolice a minha pois ficar escrevendo formularios e formularios só serviu para me dar trabalho(PENA =[ ), mas é fazendo "merda" que vamos aprendando não é? 

Só não faça merda com o sistema de um cliente... faça isso com suas experiências é melhor e mais seguro.

Quando vc baixa o Quickstart do zend framework por padrão ele já te da um diretório com o nome forms e vem até um exemplo de formulario com instancias de outras classes do zend, mas acredito que para um iniciante a curva de aprendizagem é longa quando ve uma classe pronta com tanta coisa... por conta disso vamos criar uma nova.

Nesse diretorio forms crie um arquivo chamado Exemplo.php e nele insira esse conteudo:

1. <?php
2. class Application_Form_Exemplo extends Zend_Form {
4.     public function init() {
6.         $titulo = new Zend_Dojo_Form_Element_ValidationTextBox('titulo');
7.         $titulo->setLabel('titulo')
8.                  ->setRequired(true)
9.                 ->setRegExp("[\w\d]*");        
11.         $submit = new Zend_Dojo_Form_Element_SubmitButton('Enviar');
12.         $this->addElements(array($titulo, $submit));
13.     }
14. }
15. ?>

O que fizemos ai foi simples, criamos uma classe Exemplo mas o nome dela foi dado de acordo com o diretório (Application/Forms/Exemplo) justamente para o ZF carrega-la sem precisar de malditos includes e essa classe extende da Zend_Form que tem diversos métodos para formulario.

Criamos um método init que é o construtor dessa classe e nele inserimos um input titulocom alguns métodos que definem label, obrigatoriedade e expressão regular respectivamente.
Criamos o objeto $submit passando seu nome para o construtor da classe SubmitButton e por fim adicionamos esses caras no formulario completo.

Mas e como eu faço para colocar isso na view?

Esse trabalho é bem simples... vá para o seu controller index na action index que é onde vamos chamar esse carinha e fica bem simples olha:

2.      public function indexAction() {
3.         $formulario = new Application_Form_Modelo();
4.         $formulario->setAction('index/teste');
5.         $this->view->formulario = $formulario;
6.     }

Veja que nesse action fizemos algo muito simples, criamos um objeto $formulario que é instancia da classe que criamos(do nosso formulario) e setamos um local para onder esse form será enviado e por fim mandamos ele para a view...

E ai na view é só exibir essa criança (echo $this->formulario;) pronto, formulario pronto e podemos reutiliza-lo em qualquer lugar, podendo mudar o destino e ainda adicionar elementos, validações e etc...

Não entrei a fundo sobre as validações, formatação do formulario pois a ideia era mostrar de forma simples como ele funciona caso vc queira um estudo aprofundado nesses caras a documentação do zend esta mt boa ou ainda veja nesse blog onde o autor fala mt bem dos decorators do zend form: blog 

Bem pessoal por hoje é só.... valeu!