Análise e Projetos

de Sistema
 Material Teórico
Documentação de Projetos

Responsável pelo Conteúdo:

Prof. Ms. Rodrigo da Rosa

Revisão Textual:
Profa. Dra. Patrícia Silvestre Leite Di Iório
 Documentação de Projetos

• Introdução

• Documentação de Projetos de Software

• Modelo de documentação

·· • Quais são os motivos que determinam a importância de se

documentar um projeto de software?
·· • Como são descritas as etapas necessárias para a elaboração
de documentos de projeto de software?
·· • Como são descritos os modelos de documentação utilizados como
referência para confecção de manuais e outros documentos?

Para que os objetivos da unidade sejam alcançados, é fundamental que você leia
cuidadosamente todo o material e realize com atenção todas as atividades propostas.
Nesta unidade, é importante que, durante as leituras e realização dos exercícios, você consiga
compreender a importância de se documentar os processos envolvidos no desenvolvimento
do projeto de software.
Sugerimos que você acesse e leia cuidadosamente o material teórico.
Após isso, você poderá acompanhar a Apresentação Narrada, pois ela lhe ajudará a
compreender melhor os principais assuntos da Unidade.
Outro recurso fundamental é a atividade de sistematização, já que com ela você poderá
perceber o quanto aprendeu sobre o tema.
É importante realizar a atividade de aprofundamento, que associa os assuntos que estudamos
a atividade profissional por meio de uma reflexão sobre o tema.
Além disso, você contará com textos e/ou vídeos indicados no material complementar.

5
 Unidade: Documentação de Projetos

Contextualização

Documentar um projeto de software deixou de ser uma recomendação e passou a ser uma
exigência, principalmente se estivermos nos referindo ao desenvolvimento de um sistema que
envolve níveis consideráveis de complexidade.
Este procedimento deve ocorrer desde os primeiros contatos entre os analistas e
usuários/clientes, havendo o especial cuidado para que nenhuma informação importante
se perca durante todo o processo.
A documentação deverá conter descrição dos requisitos levantados junto aos usuários/
clientes. Além disso, serão descritos os modelos, técnicas empregadas, os diagramas elaborados
para melhor representar o fluxo de informações relacionado ao projeto, os códigos-fonte, a
equipe que se dedicou a este trabalho, duração, objetivos etc.
Nesta unidade, iremos abordar sobre as características de uma documentação, baseadas
em um modelo que busca atender de maneira completa a formatação do documento de
software em relação aos elementos essenciais necessários para que o usuário/cliente tenha
condições de se orientar no que diz respeito ao sistema e também para que outras pessoas,
por exemplo, desenvolvedores que não participaram do desenvolvimento ou ainda a equipe
de manutenção tenham condições suficientes para entender o sistema e executar as ações
que desejarem ou precisarem executar.

6
 Introdução

Desde a fase inicial de desenvolvimento de um projeto de sistemas à fase de levantamento de

requisitos, diversas informações relevantes são transmitidas, seja do usuário para o analista ou
do analista para a equipe de criação. Cada uma destas informações deve ser tratada de modo
a servir como parâmetro para a estruturação do projeto, uma vez que é a partir disso que os
objetivos gerais poderão e deverão ser contemplados.
A documentação envolve o registro de todas as conversas, ações, solicitações, objetivos,
dentre outros, que visam a detalhar ao máximo o projeto para que fique muito claro o que existe
na atual situação, o que se espera como solução dos problemas enfrentados e as ações utilizadas
para que os requisitos sejam atendidos.
Nesta unidade, abordaremos os conceitos, técnicas e referências envolvidos na elaboração
de documentos que descreverão o software, seu funcionamento, suas aplicações, dentre outros.
Além disso, é necessário que haja a percepção da importância de se documentar os projetos de
sistemas, devendo considerar que existem diversas pessoas envolvidas, como os usuários finais,
o analista, os desenvolvedores e os engenheiros de sistema.

Documentação de Projetos de Software

Documentar o projeto de um software nem sempre é algo que os desenvolvedores mais gostam
de fazer. Geralmente, são profissionais altamente técnicos, uma vez que estão em contato com
códigos-fonte, funções, instruções etc. e assumir uma escrita que permita uma compreensão
fácil daquilo que está sendo desenvolvido não é uma tarefa simples. Além disso, existe para eles
tamanha responsabilidade referente ao desenvolvimento, pois precisam usar com grande atenção
suas habilidades para que o software consiga atender aquilo que foi exigido pelo usuário. Muitas
vezes, as empresas que projetam sistemas optam por constituir uma equipe exclusiva para a tarefa
de documentar, trabalhando muito perto dos engenheiros de software/sistema.

Mas, afinal, a documentação é realmente necessária?

Documentar um sistema é de extrema importância em projetos de software. Os documentos

descreverão todas as funcionalidades do software, suas relações com outros sistemas, as técnicas
empregadas, as linguagens utilizadas, as etapas de construção, os requisitos levantados, os
planos traçados dentre outros.

Os softwares serão utilizados por pessoas que não o desenvolveram. Elas, possivelmente,
terão conhecimento do que o software precisa fazer, afinal é para este fim que são levantados
os requisitos. Entretanto, é somente isso o que saberão de um sistema complexo. Além disso:

7
 Unidade: Documentação de Projetos

• Diversas pessoas trabalham no processo de desenvolvimento do software, desde o

analista até a equipe toda que está empenhada na construção deste sistema;
• Durante a construção do software ocorrem pequenas ou grandes evoluções, alterações
e ajustes em códigos, diagramas, tabelas etc. Caso algo não seja descrito, outras pessoas
terão dificuldades em captar o que foi feito e por que.

Vantagens de se documentar:
• A gerência terá condições suficientes para fazer planejamentos, definir orçamentos e
elaborar cronogramas;
• Toda a equipe de desenvolvimento terá uma mesma linguagem, uma vez que os integrantes/
desenvolvedores conhecerão integralmente as características que descrevem o sistema.
• Os usuários do sistema poderão conhecer o software como um todo e isto será para eles um
enorme auxílio, pois características do sistema que não são tão simples, ou telas carregadas
de botões e/ou informações estarão detalhadas em termos de demonstração de uso.

Diálogo com o Autor

Sommerville (2007, p. 91) argumenta que o processo de documentação

inclui um conjunto diversificado de usuários, desde a gerência sênior da
organização, que paga pelo sistema, até os engenheiros responsáveis pelo
desenvolvimento do software.

Kotonya e Sommerville (1998, apud SOMMERVILLE, 2007, p. 91)

apresentam a ilustração a seguir que mostra os possíveis usuários do
documento e como eles utilizam.

Figura 1: Usuários de um documento de software.

8
 Como já é de nosso conhecimento, o ciclo de vida de um software é descrito conforme figura abaixo:

Figura 2: Ciclo de Vida do Software.

A documentação de projetos se enquadra na fase de Implementação, em que todos os

documentos e manuais serão elaborados, com base em um conjunto de formulários, fichas,
relatórios gerados desde a fase inicial do projeto.
Um fato que precisa estar bem esclarecido é que qualquer projeto de software precisa de
certa quantidade de documentos que irá caracterizá-lo, demonstrar seu funcionamento etc.
O profissional responsável pela fase de implementação, no que diz respeito à documentação,
é normalmente o Engenheiro de Software / Engenheiro de Sistemas, aquele que projeta soluções
de software, possuidor de amplo conhecimento das fases que envolvem análise de requisitos e
que conta com a equipe de desenvolvimento de sistemas para criação do projeto do usuário.
A documentação de um projeto de software pode ser dividida de duas maneiras:
Documentação de usuário: diz respeito aos manuais específicos para usuários finais (que
utilizam o software para realização de uma determinada atividade) e administradores do sistema
(aqueles que irão trabalhar diretamente com o software, inclusive com configurações gerais),
contendo uma linguagem própria para este público alvo. São descritas as formas de manipulação
do sistema, o que se deve esperar dele, e também como deverá ser utilizado.
As primeiras informações devem tratar de pontos como os primeiros passos para
utilização do sistema, além de permitir a visualização de possíveis erros e as devidas
soluções para cada um deles.

9
 Unidade: Documentação de Projetos

Outra informação importante se refere ao processo de instalação do software. Os requisitos

mínimos de hardware e sistema operacional devem também ser indicados.
Documentação de sistema: trata de características técnicas detalhadas do sistema.
Descreve a arquitetura do software, código-fonte contendo os devidos comentários, fluxogramas
etc. Além disso, define quais são os diagrama estruturais ou orientados a objetos utilizados e
demonstra cada um deles. Deve conter explicações sobre o porquê, quais linguagens e que
procedimentos foram escolhidos.
É uma documentação focada no pessoal de TI ou desenvolvedores, pois aborda uma
linguagem que é familiar para quem está desta maneira acostumado.

Modelo de Documentação

A pergunta que deve passar pela sua mente neste momento é: como documentar um
projeto de software?
Na verdade, não existe uma regra que determina como deve ser elaborada ou estruturada a
documentação de software, porém alguns modelos podem ser consultados e utilizados para se
evitar falta de qualquer tipo de informação relevante acerca do sistema.

Diálogo com o Autor

Pressman (1995, pp. 475 e 476) apresenta um esboço de documentação que

é uma descrição de projeto completa de software.

Tal esboço segue a estrutura abaixo:

I Escopo.
1) Objetivos do sistema.
2) Hardware, software e interfaces humanas.
3) Importantes funções de software.
4) Bancos de dados externamente definidos.
5) Limitações e restrições importantes do projeto.
II Documentação de referência.
1) Documentação de software existente.
2) Documentação do sistema.
3) Documentos de fornecedor de hardware e de software.
4) Referência técnica.

10
 III Descrição de projeto.
1) Descrição de dados.
a) Revisão do fluxo de dados.
b) Revisão da estrutura de dados.
2) Estrutura de programa derivada.
3) Interfaces dentro da estrutura.
IV Módulos – para cada módulo:
1) Narrativa de processamento.
2) Descrição da interface.
3) Descrição da linguagem de projeto (ou outra).
4) Módulos usados.
5) Organização de dados.
6) Comentários.
V Estrutura de arquivos e dados globais.
1) Estrutura de arquivos externos.
a) Estrutura lógica.
b) Descrição de registro lógico.
c) Métodos de acesso.
2) Dados globais.
3) Referência cruzada de arquivos e dados.
VI Referência cruzada dos requisitos.
VII Provisões de teste.
1) Diretrizes de teste.
2) Estratégia de integração.
3) Considerações especiais.
VII Empacotamento.
1) Provisões especiais para overlay de programa.
2) Considerações sobre transferência.
IX Notas especiais.
X Apêndices.
Tabela 1: Esboço de documentação segundo Pressmann (1995, p. 476)

Overlay significa sobreposição. Quando tratamos do termo área de

overlay estamos nos referindo a um espaço, seja memória ou disco,
destinado para substituição periódica de programas, ou seja, a
sobreposição de um em relação a outro.

11
 Unidade: Documentação de Projetos

Na etapa I, Escopo, são documentadas informações referentes à fase inicial do projeto, ou

seja, a de levantamento de requisitos.
Fatores humanos como pessoas envolvidas e suas tarefas ou participações são apontadas.
Recursos de hardware e de software também são definidos, indicando quais são e também suas
disponibilidades, duração de uso e data de entrega.

Diálogo com o Autor

Pfleeger (2004, p. 372) comenta que um manual explica as configurações

de hardware e software, os métodos para permitir e negar o acesso de um
usuário, os procedimentos para adicionar ou excluir periféricos de um sistema
e as técnicas para duplicar ou realizar o backup de arquivos e documentos.

A autora indica ainda, baseada em Mathsoft (1995, apud PFLEEGER, 2004, p. 372), um
exemplo de configuração de teclado para edição na linha de comando:

Ação Teclas pressionadas

Chamar comando anterior Seta para cima
Próximo comando Seta para baixo
Chamar o décimo comando anterior Page Up
Chamar o primeiro comando digitado Control + page down
Chamar o décimo comando posterior Page down
Chamar o último comando digitado Control + page up
Fim da linha End
Começo da linha Home
Uma palavra anterior Control + seta para a esquerda
Uma palavra posterior Control + seta para a direita
Limpar linha de comando Esc
Apagar o caractere à esquerda do cursor Backspace
Apagar o caractere à direita do cursor Delete
Inserir no local do cursor Digitar caracteres desejados
Selecionar o caractere à esquerda do cursor Shift + seta para a esquerda
Selecionar o caractere à direita do cursor Shift + seta para a direita
Selecionar até o final da linha Shift + end
Selecionar desde o começo da linha Shift + home
Procurar pelo texto selecionado Tecla de função 8
Copiar o texto selecionado para a área de transferência Control + delete
Recortar o texto selecionado para a área de transferência Shift + delete
Excluir o texto selecionado Delete
Tabela 2: Teclas para edição na linha de comando.

12
 Não se pode esquecer da definição do banco de dados que será utilizado, bem como do
sistema que irá gerenciá-lo para que haja interação com outros sistemas utilizados pelo usuário.

Constitui a documentação dos requisitos, segundo Sommerville (2007, p. 93):

• um prefácio, indicando o seu público-alvo, a justificativa para o desenvolvimento do

sistema e ainda um breve relato, ou resumo, contendo os objetivos gerais do sistema e o
que se espera dele;

• uma introdução, que descreve brevemente as funcionalidades do sistema e seu

funcionamento em conjunto com outros. Deve descrever como o sistema atende aos
objetivos gerais de negócios e estratégicos da empresa que o solicitou;

• um glossário, que apresentará os termos técnicos inseridos no documento;

• uma definição dos requisitos funcionais e não-funcionais do sistema.

Na etapa II, Documentação de referência, são demonstradas características mais técnicas

do sistema e as soluções sugeridas para implementação. Aborda questões importantes sobre o
software desenvolvido, sobre o sistema como um todo, incluindo sistema operacional e sistema
gerenciador de banco de dados.

Além disso, deve constar informações sobre fornecedores de hardware e software e também
seus respectivos manuais.

A etapa III, Descrição do Projeto, deve contemplar a estrutura do fluxo de dados

existente nos modelos utilizados. São apresentados os modelos estruturados (diagrama
de fluxo de dados, diagrama entidade-relacionamento, dicionário de dados) e os modelos
orientados a objetos (diagramas de caso de uso, de classe de objeto, de interação, de
atividade etc.) que foram elaborados para melhor descrever as maneiras como os dados
são tratados durante sua “vida” no sistema.

As interfaces na estrutura do software são apresentadas também nesta seção, permitindo

a visualização de menus, métodos de ajuda, caixas de diálogo, botões etc. São elas que
se comunicarão com o usuário através de códigos e mensagens geradas pelo programa
durante a sua manipulação.

Os Módulos, da etapa IV, são estruturas de programação que fazem parte do código geral
do programa, porém são independentes em suas ações. Denominadas muitas vezes de funções,
procedimentos ou sub-rotinas que são executadas pelo programa sempre em resposta a uma
ação do usuário ou solicitação do sistema.

Cada módulo apresentado e explicado por uma narrativa de processamento, indicando a

atividade que irá executar caso seja acessado.

A interface gerada por estes módulos também deve ser detalhada objetivando o esclarecimento
sobre as funcionalidades do software como um todo.

13
 Unidade: Documentação de Projetos

A maneira como os dados são organizados e a(s) linguagem(ns) utilizada(s) para o

desenvolvimento do projeto de software deverão compor esta etapa da documentação. Isso dará
às pessoas que farão manutenção ou às que manipularão o sistema condições de resolverem
problemas de maneira mais rápida e adequada no momento em que surgirem, além do fato de
que poderão conhecer mais profundamente as ferramentas que estarão disponíveis para eles.
Comentários são sempre muito bem-vindos.

Diálogo com o Autor

Pfleeger (2004, p. 264) considera que o formato dos comentários

pode ajudar um leitor a entender o objetivo do código e como ele
é atingido. O recuo e o espaçamento entre linhas de código podem
refletir a estrutura de controle básica.

O autor apresenta um exemplo, conforme abaixo:

if (xcoord < ycoord)

result = -1;
elseif (xcoord == ycoord)
if (slope1 > slope2)
result = 0;
else result = 1;
elseif (slope1 > slope2)
result = 2;
elseif (slope1 < slope2)
result = 3;
else
result = 4;

A estrutura do código pode se tornar mais clara, se utilizarmos o recuo e reorganizarmos o espaço:

if (xcoord < ycoord) result = -1;

elseif (xcoord == ycoord)
if (slope1 > slope2) result = 0;
else result = 1;
elseif (slope1 > slope2) result = 2;
elseif (slope1 < slope2) result = 3;
else result = 4;

14
 Com relação aos comentários, o autor continua descrevendo o exemplo abaixo:

void free_store_empty()
{
static internet i = 0;
if (i++ == 0)
// alerta contra erro
cerr << “out of memory\n”; // na alocação de memória
abort(); // diz ao usuário, desiste.
}

O que está destacado no código acima são os comentários.

A etapa denominada Estrutura de arquivos e dados globais, etapa V, demonstra uma
relação com o item anterior. São descritos minuciosamente quais são os arquivos (e suas
características) armazenados em CDs ou DVD, dentre outros, e também os métodos de acesso
a eles. Os dados globais, que são o conjunto de dados que caracterizam o software, também
estão relacionados aqui e aparecem organizados em forma estruturada e lógica. Após esta
estruturação, uma referência cruzada é estabelecida entre os módulos (sub-rotinas, funções etc.)
do software e os arquivos existentes no projeto.

Referência cruzada é uma técnica utilizada em documentos para indicar

a relação entre dados e/ou informações que estão, geralmente, em locais
diferentes em tais documentos. Em alguns editores de texto, a referência
cruzada é conhecida como hyperlink.

Em Referência cruzada dos requisitos, na etapa VI, é uma maneira de documentar como os
objetivos dos usuários, em relação ao sistema, estão sendo atendidos.
Módulo C
Módulo A
Módulo B

Módulo Z
...

Parágrafo 3.1.1 X X
Parágrafo 3.1.2 X X
Parágrafo 3.1.3 X
...
Parágrafo 3.m.n X X
Tabela 3: Referência cruzada de requisitos (PRESSMAN, 1995, p. 478).

Podemos, deste modo, perceber que as inscrições do tipo parágrafo (parágrafo 3.1.1,
parágrafo 3.1.2 etc.) são os itens que descrevem cada um dos requisitos levantados na primeira
fase de desenvolvimento do projeto de software. Tais requisitos estão associados a, pelo menos,

15
 Unidade: Documentação de Projetos

um módulo devidamente descrito. Assim, entende-se que um determinado requisito está sendo
atendido por certo procedimento existente na programação do software.
A etapa VII, Provisões de teste, descreve diretrizes que ajudarão os profissionais que
trabalharão diretamente com o software a realizar testes no sistema. Tais diretrizes auxiliarão
na captação de possíveis defeitos. Nesta seção são apresentadas também as estratégias de
integração do sistema como um todo, ou seja, de que forma o software projetado se “comunica”
com o sistema gerenciador de banco de dados, por exemplo.
Empacotamento é a definição da etapa VIII. A respeito do empacotamento, Pressman
(1995, p. 477) esclarece:

Diálogo com o Autor

Considerações especiais causadas pela necessidade de overlay do

programa, gerenciamento de memória virtual, processamento de alta
velocidade ou outros fatores podem provocar uma modificação do
projeto, derivada do fluxo de informação ou da estrutura. Além disso,
essa seção descreve a abordagem que será usada para se transferir o
software para o local do cliente.

Nesta etapa, são descritas as possíveis restrições que o software poderá ter, com respeito à
capacidade de alocação em memória, vulnerabilidade, considerações sobre transferência ou
compatibilidade com outros sistemas e/ou aplicativos.
As etapas IX e X, Notas especiais e Apêndice, são utilizadas para anexos de documentos
extras, ou seja, informações complementares relacionados ao sistema, como por exemplo, um
manual de instalação do sistema.
Exemplo básico de parte de uma documentação, baseado em Guedes
(2009, pp. 373 a 385).

• Diagrama de caso de uso de venda.

Figura 3: Diagrama de caso de uso para vendas.

16
 Diagramas de caso de uso, assim como diversos outros diagramas, são descritos em uma
documentação de sistema.
• Tabelas de referência aos diagramas de caso de uso.

Caso de uso: Identifica-se

Ator Cliente
Outros atores
Resumo Descreve os procedimentos realizados por um cliente
para fazer login no sistema.
Condições Deve estar cadastrado no sistema.
Ações do ator Ações do sistema
1) Selecionar a opção Identificação.
2) Apresentar a seção de login e senha.
3) Preencher login e senha.
4) Verificar cliente cadastrado e autenticá-lo.
Fluxo secundário
1)Se o cliente não estiver cadastrado deverá ser
executado o módulo Cadastrar.
Tabela 4: Documentação referente ao diagrama de caso de uso – Identifica-se.

Caso de uso: Escolhe CD

Ator Cliente
Outros atores
Resumo Descreve os procedimentos realizados por um cliente
para escolha de um CD.
Condições
Ações do ator Ações do sistema
1) Selecionar a opção Escolher CD.
2) Apresentar os CDs disponíveis, ordenando,
inicialmente, por lançamentos.
3) Adicionar CD no carrinho.
4)Realizar armazenamento do CD ao pedido.

Fluxo secundário

Tabela 5: Documentação referente ao diagrama de caso de uso – Escolhe CD.

17
 Unidade: Documentação de Projetos

Caso de uso: Escolhe DVD

Ator Cliente
Outros atores
Resumo Descreve os procedimentos realizados por um cliente
para escolha de um DVD.
Condições
Ações do ator Ações do sistema
1) Selecionar a opção Escolher DVD.
2)Apresentar os DVDs disponíveis, ordenando,
inicialmente, por lançamentos.
3) Adicionar DVD no carrinho.
4)Realizar armazenamento do DVD ao pedido.
Fluxo secundário

Tabela 6: Documentação referente ao diagrama de caso de uso – Escolhe DVD.

18
 Material Complementar

COMPUTERWORD. Disponível em http://computerworld.uol.com.br/.

PAULA FILHO, W. P.. Engenharia de Software: fundamentos, métodos e padrões. Rio

de Janeiro. LTC, 2009.

PRESSMAN, R. S.. Engenharia de Software. São Paulo. Pearson, 2011.

19
 Unidade: Documentação de Projetos

Referências

GUEDES, G. T. A. UML 2: uma abordagem prática. São Paulo. Novatec, 2009.

KOTONYA, G. & SOMMERVILLE, I. Requiriments engineering: processes and techniques,

1998. In: SOMMERVILLE, I. Engenharia de Software. São Paulo. Pearson, 2007.

MATHSOFT. S-PLUS. User´s manual, version 3.3 for Windows. Seattle, WA: Mathsoft
Corporation, 1995. In: PFLEEGER, S. L. Engenharia de software: teoria e prática. São
Paulo. Prentice Hall, 2004.

PAULA FILHO, W. P. Engenharia de software: fundamentos, métodos e padrões.

Rio de Janeiro. LTC, 2009.

PFLEEGER, S. L. Engenharia de software: teoria e prática. São Paulo. Prentice Hall, 2004.

SOMMERVILLE, I. Engenharia de Software. São Paulo. Pearson, 2007.

20
Anotações

21
22
www.cruzeirodosulvirtual.com.br
Campus Liberdade
Rua Galvão Bueno, 868
CEP 01506-000
São Paulo SP Brasil
Tel: (55 11) 3385-3000