Diferenças entre documentação de Projeto, de Sistema e de Usuário

Este artigo pretende esclarecer alguns pontos importantes que deveria constar em cada uma das documentações necessárias para o desenvolvimento de um projeto de software.

por Rosane Marchand

Definições

Muito se ouve falar sobre a importância de documentar projetos de software. Porém existe uma diferença entre documentação de projeto, documentação de sistemas e documentação de usuário. O importante é definir claramente o que seria um projeto e como se encaixa um sistema no mesmo. Posteriormente falaremos sobre documentação de usuário.

Vamos às definições de projeto e de sistema.

Projeto pode ser simplesmente definido como o plano para construção de um produto ou serviço, que na matéria abordada será o software, ou sistema.  Como todo plano, para que o objetivo seja alcançado, deverá existir um planejamento.

No nosso caso, o planejamento nada mais é do que a documentação do projeto em si. O produto resultante da aplicação do plano do projeto será o próprio sistema.

Este artigo pretende esclarecer alguns pontos importantes que deveria constar em cada uma das documentações necessárias para o desenvolvimento de um projeto de software.

Documentação de Projeto, de Sistema e de Usuário

Primeiramente devemos esclarecer quais os tipos de documentações, que devem ser desenvolvidos para o projeto e para produto resultante deste, que pode ser um ou mais sistemas.

Vamos adotar que para o restante do artigo, estejamos tratando de um projeto para um único sistema.

Para que o nosso sistema possa ser desenvolvido no menor prazo, com menor custo operacional e maior confiabilidade, temos que definir a estratégia para cada etapa do desenvolvimento.

O que acontece na prática, na maioria das empresas desenvolvedoras de produtos de software.

O cliente solicita um sistema com base no que ele acha que seria o ideal para otimizar um determinado processo da sua empresa. Elabora uma documentação do que ele deseja que seja desenvolvido. Com base nesta documentação e em algumas entrevistas com o cliente, teremos uma idéia do que deve ser feito.

Não vamos entrar no mérito se este processo é o correto. A questão aqui é manter o foco nas documentações a serem produzidas para cada etapa do processo de desenvolvimento do produto.

Com base no levantamento das regras do negócio a ser desenvolvido, deve-se elaborar uma documentação mínima, que servirá de diretriz para o desenvolvimento, homologação e implantação do sistema.

Normalmente é estimado um prazo, com base nas funcionalidades levantadas da documentação e das entrevistas. Cada funcionalidade irá demandar um esforço das equipes envolvidas, possui uma complexidade agregada e um risco envolvido, que pode ser do negócio, da implementação ou da implantação (normalmente quando há integração com sistemas legados).

A documentação, desta etapa, é somente a documentação referente ao projeto, ou seja, documentação do plano de ação para o desenvolvimento do sistema solicitado.

Nesta fase, a documentação está mais relacionada com os aspectos burocráticos do negócio, como por exemplo, contratos, cronograma, planilhas de custo e controle, plano de teste e de homologação e plano de implantação.

As fases de implementação, homologação e implantação do projeto baseiam-se no definido nestes documentos, especialmente no cronograma e nas planilhas de controle, que pode ser o gerenciamento das atividades da equipe.

Em alguns casos, a definição da arquitetura do sistema e as métricas calculadas, que resultam na definição do cronograma, podem ser agregados à documentação do projeto.

Temos que ter me mente que cada empresa segue seu próprio processo interno, portanto o que é de praxe em uma empresa não necessariamente se aplica à outra.

O objetivo desta matéria é exibir uma idéia do que seria interessante de ser adotado pelas empresas que buscam melhorias nos seus processos de desenvolvimento de software ou que pecam no quesito documentação de projeto e sistema.

De todos os documentos elaborados para esta fase do projeto, alguns poderão ser documentos entregáveis ao cliente, como por exemplo, o levantamento dos requisitos, as métricas aplicáveis, que resultam na elaboração do cronograma, os planos de teste e homologação (com as evidências resultantes) e o plano de implantação.

Nem todos os documentos de projeto são documentos entregáveis ao cliente. Depende do acordo definido entre as partes envolvidas.

Normalmente, os documentos entregáveis são aqueles relacionados àquilo que o cliente poderá usar como facilitador de uso do produto.

Vamos tomar como exemplo as empresas desenvolvedoras de softwares. Quando o cliente compra o produto, a única documentação que, por lei deverá constar no produto, são as documentações referentes ao uso, como manuais de instalação e configuração, manual de usuário, informações para solicitação de ajuda, troca e substituição e informações sobre os requisitos necessários de uso.

Isso significa que elas não desenvolvem outros tipos de documentação?

NÃO. Significa que, para o USO do produto, este tipo de documentação é suficiente.

Por outro lado, a documentação do sistema a ser desenvolvido, deve ter como foco tudo que envolve a implementação, teste e homologação e implantação do sistema em si.

A documentação do sistema deve servir como diretriz às equipes envolvidas, de modo a que estas mantenham o foco no que deve ser feito e como deverá funcionar.  

O gerenciamento destas equipes resultará na alteração contínua da documentação do projeto, pois nem sempre o planejado é igual ao realizado.

Devemos ter em mente que toda documentação é um artefato “vivo”, ou seja, mesmo depois de um produto finalizado, cada erro encontrado e reportado à empresa, alterará os documentos, tanto de projeto quanto de sistema, podendo refletir, na documentação de usuário.

O objetivo de se elaborar a documentação do sistema para as equipes envolvidas no seu desenvolvimento é unicamente a de definir o que e como deve ser feito e como deve funcionar.

Para o cliente, elaborar a documentação, além de agregar valor ao produto, passa a idéia de profissionalismo, ao invés de amadorismo. Outra questão muito importante, que muitas vezes não é devidamente usada é a delimitação do que será o produto a ser entregue, controlando desta forma as expectativas do cliente com relação ao seu sistema.

Quando não há uma documentação, o cliente saberá se aproveitar disso para fazer recorrentes solicitações de alteração, podendo, desta forma, comprometer seriamente o que foi acordado entre as partes, resultando em atrasos, impactando na lucratividade da empresa e diminuindo a moral da equipe.

Os documentos que podem ser gerados para o desenvolvimento são vários, podendo ser textuais ou diagramais.

Abaixo segue uma tabela com todos os possíveis documentos que podem ser elaborados para cada etapa do processo de desenvolvimento, desde a implementação até a implantação.

Etapas / Tipos de Documentos	Textuais	Diagramais
Implementação	Documento de Visão do Negócio. Descrição dos Casos de Uso. Descrição dos Requisitos. Descrição das Classes e Objetos. Descrição dos processos. Documentação técnica – funcionalidades e relação de entrada, manipulação e saída de dados. Dicionário de Dados. Modelo de Integração de Sistemas. Documento de Serviços de Negócio.	Diagrama dos Casos de Uso. Diagrama das Entidades e seus Relacionamentos – MER. Diagrama de Classes e Objetos. Diagrama de Seqüência. Diagrama de Atividades. Diagrama de Processos. Diagrama do Modelo de Integração.
Testes (***)	Plano de Testes Unitários. Plano de Testes Funcionais. Evidências de testes. (*)	Não se aplica. (**)
Homologação (***)	Plano de Homologação. Plano de Validação de Entradas e Saídas. Evidência de Validação. (*)	Não se aplica. (**)
Implantação (***)	Plano de Implantação.	Não se aplica. (**)

(*) Os documentos de evidência de testes e validação, são gerados como resultados da execução dos respectivos planos.

(**) O fato de não ser aplicável, não significa que cada empresa não possa ou não deva elaborar seus diagramas para estas etapas.

(***) As etapas de Testes e Homologação baseiam seus planos nos documentos da etapa de Implementação. A etapa de implantação tem como base, os documentos do modelo de arquitetura, mas pode se basear nos documentos da etapa de Implementação.

A tabela acima exibe os tipos de documentação que podem ser elaborados para o desenvolvimento do produto de software.

O modelo e a adoção de um tipo em detrimento de outro fica, única e exclusivamente a cargo da empresa.

Pode ocorrer de o cliente solicitar um tipo de documentação que siga seus padrões de definição, e que esta lhe seja entregue ao término do projeto. Cada situação é uma situação a ser analisada, e que depende do acordo entre as partes.

Documentação de sistema por via de regra não é do tipo entregável, a menos que isso tenha sido acordado.

Toda empresa deveria manter o historio dos seus projetos, baseado nas documentações produzidas. A experiência advinda deste histórico servirá como base para projetos futuros, por favorecerem o processo de melhoria contínua de seus processos internos, evidenciando quais os cases foram assertivos e quais não foram.

Basear seus projetos futuros com base em projetos históricos, garante maior competitividade no mercado, por garantir ao cliente um produto de melhor qualidade, menor custo e prazo e maior lucratividade, tanto para os clientes, quanto para a empresa e suas equipes.

Por fim, vamos abordar a documentação do usuário.

Esta documentação é do tipo entregável e refere-se unicamente a como o usuário pode usar o produto desenvolvido.

Devemos ter em mente, que nem todos os projetos geram documentação de usuário, mas certamente deverão gerar documentação de projeto e de sistema.

Alguns documentos do sistema podem servir como base para a documentação do usuário, como por exemplo, o documento dos casos de uso.

Uma vez definido, os fluxos de usabilidade do produto, isso poderá ser útil na construção do manual do usuário, por exemplo.

Resumindo, além de todas as vantagens de se documentar um projeto e o sistema, as documentações podem e devem ser reaproveitadas nas diferentes etapas, gerando menor esforço na produção das mesmas.