FATEC - OURINHOS

Profa. Me. Viviane de Fatima Bartholo Potenza

viviane.potenza@fatecourinhos.edu.br

Engenharia de Software II

Introduo a Documentao
de Software
e
Padres Utilizados nas
Documentaes

A Documentao de Software
Necessidade ou preciosismo?

A documentao de software, mesmo sendo o carma de

qualquer desenvolvedor, extremamente necessria e auxilia
na reduo de horas preciosas na correo de problemas.

Para muitos desenvolvedores, a criao de documentao

tcnica a parte mais aterrorizante para se enfrentar em todo o
processo de criao de um software.

Necessidade de escrever vrias e vrias pginas de texto,

grficos e desenhos.
Vdeo: levantamento de requisitos

Documentao, o que ?

A documentao de um software composta por vrias partes

diferentes que abrangem todo o sistema e pode ser dividida em dois
grandes grupos: documentao tcnica e documentao de uso.

Tcnica voltada ao desenvolvedor ou pessoa de TI e compreende

principalmente dicionrios e modelos de dados, fluxogramas de
processos e regras de negcios, dicionrios de funes e comentrios
de cdigo.

De uso voltada tanto para o usurio final quanto para administrador

do sistema, formada por apostilas ou manuais que apresentam como
o software deve ser usado, o que esperar dele e como receber as
informaes que se deseja.

Ambas podem ser criadas em formatos de visualizao como: pginas HTML,

documentos PDF, apresentaes, vdeos ou ainda arquivos texto.

Contexto da Documentao

Qualquer software deve ter uma quantidade

documentao.
Documentos de trabalho.
Manuais de usurio produzidos profissionalmente.

razovel

de

Em geral, a maioria destes documentos produzida por engenheiros

de software.

Uma parte considervel dos custos de um projeto pode ser gasta com
documentao.

documentao to importante (ou mais) que as questes de

segurana.

Usos da Documentao

Meio de comunicao
desenvolvimento;

entre

os

membros

de

um

grupo

de

Informaes gerncia de modo a ajudar a planejar, fazer o oramento e

o cronograma;

Informaes para ensinar aos usurios como utilizar e administrar o

sistema.

Informaes para as pessoas que venham a fazer manuteno no

sistema;

Tipos de Documentao

Documentao do processo
produzida para que o processo de desenvolvimento do software seja
administrvel
Registram os processos de desenvolvimento e manuteno do
software

Documentao do produto
Descreve o software que est sendo desenvolvido
muito utilizada depois que o sistema implementado, mas
essencial tambm para a administrao do processo de
desenvolvimento
7

Estudo de
Caso

Processos

Estudo de Caso
Processos

(verificar o contexto, neste caso estamos falando dos processos de

um software (produto))

Cadastrar

hotis
Efetuar reserva
Cadastrar clientes
Cadastrar acomodaes
Cadastrar usurio
Gerenciar reserva

Documentao do Processo

Processo de Software:

Enfoca os processos de software,

os elementos que compem um processo,
a definio de processos para projetos,
modelos de processo,
normas e modelos de qualidade de processo de software
e a automatizao do processo de software.

O processo de software pode ser definido como um conjunto de

atividades, mtodos, prticas, e transformaes que as pessoas
empregam para desenvolver e manter software e os produtos
associados (ex. planos de projeto, documentos de projeto
(design), cdigo, casos de teste, e manual do usurio).[PAULK95]

Documentao do Processo
Um processo de software o que define
quais atividades devem ser realizadas dentro de uma
produo de sistemas, define tambm as pessoas
envolvidas e os artefatos a serem gerados. J
o modelo de processo de software define a
sequncia com que as atividades so executadas e
quais as pessoas esto envolvidas e quais os
artefatos so gerados por cada atividade.

Documentao do Processo - Categorias

Planos, estimativas, e cronogramas

Produzidos por gerentes
Usados para prever e controlar o processo.

Relatrios
Descrevem como os recursos foram utilizados durante o
desenvolvimento do software

Padres
Estabelecem como o processo deve ser implementado
Podem ser organizacionais, nacionais, ou internacionais
12

Documentao do Processo - Categorias

Memorandos, comunicaes, mensagens eletrnicas

Registram as comunicaes entre gerentes e engenheiros de
software

Documentos tcnicos de trabalho

Registram as idias e pensamentos dos engenheiros de
software.
Descrevem estratgias de implementao.
Registram problemas j identificados.
Especificam as razes para as decises de projeto.

13

Documentao do Produto

Descreve o software produzido.

Tem vida longa e deve estar sempre atualizada em relao ao

cdigo.

Divide-se em:
Documentao do sistema.
Documentao do usurio.

14

Documentao do Produto
- Documento do Usurio
Deve levar em conta os diversos tipos de usurios.
Exemplo:
Usurios finais

Usam o software para auxili-los em alguma tarefa

No esto interessados em detalhes tcnicos ou administrativos.

Administradores do sistema

Responsveis pela administrao do software

Ex: operadores, gerentes de rede, etc.

Documentao do Produto
- Documento do Usurio
Descrio funcional do sistema

Requisitos gerais do sistema

Servios fornecidos por ele

Manual de introduo

Apresenta uma introduo informal do sistema e descreve seu

uso normal
Deve explicar como comear a usar o sistema e como os
usurios podem utilizar as facilidades oferecidas pelo sistema

Documentao do Produto
- Documento do Usurio
Manual de referncia

Informaes concisas das principais funes do sistema e como

utiliz-las
Fornece uma lista das mensagens de erro mais comuns e descreve
como agir quando os erros ocorrerem
Deve ser completo e tcnicas de descrio formal podem ser
utilizadas

Documento de instalao

Descreve como instalar o sistema

Especifica a plataforma mnima necessria sua instalao

Documentao do Produto
- Documento do Usurio
Manual do administrador do sistema.

Informaes relevantes para uma boa administrao do

sistema

Ajuda on-line

Documentao do Produto
- Documento do Sistema

Descreve a implementao do sistema, desde a

especificao dos requisitos at o plano de testes.

importante que seja estruturada com overviews

levando a especificaes mais detalhadas e formais de
cada aspecto do sistema.

Documentao do Produto
- Documento do Sistema

Documento de requisitos
Descrio da arquitetura do sistema
Descrio da arquitetura de cada um dos programas
Listagens do cdigo fonte dos programas
Documentos de validao, descrevendo
Como cada programa validado
Como estas informaes se relacionam com os requisitos
Guia de manuteno
Problemas j identificados
Partes do sistema que so dependentes do hardware e
software utilizados

Documentao do Cdigo

Pode ser extremamente til

entendimento dos programas:
Escolha de nomes;
Organizao visual;
Comentrios.

para

melhorar

21

(facilitar)

Documentao do Cdigo
- Escolha de Nomes

Os nomes devem ser significativos em relao ao que eles

representam.

Identificadores maiores melhoram a compreenso dos programas,

mesmo em programas pequenos.

Identificadores grandes demais dificultam sua digitao e podem

se tornar uma fonte de erros.

Documentao do Cdigo
- Organizao Visual

Maneira como o cdigo aparece na tela do computador ou em

uma listagem.

Os padres de boa codificao mais aceitos incluem:

Um nico comando por linha;
Espaamento entre os componentes dos comandos;
Identao.

Documentao do Cdigo
- Comentrios

Devem ser usados para explicar o que o software faz, ao invs de

como ele faz.

Duas formas de comentrios so mais comuns:

Comentrios em forma de prlogo;
Comentrios funcionais.

Documentao do Cdigo
- Comentrios em Forma de Prlogo

Aparecem no incio de cada mdulo.

Formato:
Declarao de propsitos;
Descrio da interface com outros mdulos:
Forma

de uso;
Quais os mdulos subordinados;
etc.

Pequena descrio dos dados, variveis, limitaes de uso, e

quaisquer outras informaes que sejam importantes.

Documentao do Cdigo
- Comentrios em Forma de Prlogo

Histrico do seu desenvolvimento

O nome do autor.
A data em que foi criado.
Para cada uma das modificaes feitas no mdulo:
O

nome do revisor;
A data de alterao;
Uma descrio da alterao.

Documentao do Cdigo
- Comentrios Funcionais

Encontram-se embutidos no cdigo fonte.

Descrevem as funes de processamento.

Devem fornecer algo a mais do que simplesmente parafrasear o

cdigo.

Bons comentrios:
Descrevem blocos de cdigo ao invs de comentar cada uma
das linhas.
Usam linhas em branco e identao para que o texto dos
comentrios seja facilmente identificvel.
So corretos.

Exerccios
Exemplo de trecho de algoritmo mal escrito.

soma 0;
i 1;
enquanto i < 18 faa
soma soma + i;
i i +1;
fimenquanto
escreva (soma);

28

Exerccios
Exemplo de trecho de algoritmo mal escrito.

soma 0; { atribui o valor 0 varivel soma}

i 1;
{ atribui o valor 1 varivel i }
enquanto i < 18 faa{enquanto i no ultrapassar o valor 18}
soma soma + i; {soma vale soma mais o valor de i}
i i +1;
{ i recebe i incrementado de 1}
Fimenquanto
escreva (soma);

{ exiba o valor de soma }

29

Exerccios
Exemplo de trecho de algoritmo bem escrito.
{ faz a soma dos nmeros inteiros de 1 a 18 }
{ Autor: Viviane data: 12/02/2010}
soma 0; { o somatrio }
i 1;
{ nmero inteiro gerado }
enquanto i < 18 faa{ gera os nmero inteiros e calcula o somatrio }
soma soma + i;
i i +1;
fimenquanto
escreva (soma);

30

Qualidade dos Documentos

A qualidade da documentao to importante quanto a

qualidade do cdigo.

Aspectos importantes para se conseguir produzir bons

documentos incluem:
Planejamento (ou projeto) dos documentos;
A existncia de padres a serem seguidos;
Procedimentos de garantia de qualidade.

Padro do Processo de
Documentao

Procedimentos de desenvolvimento:
Ferramentas;
Procedimentos de qualidade.

Flexveis para lidar com todos os tipos de documentos;

Padro de Documentao

Aplicam-se a todos os documentos (de um projeto)

Identificao;
Estrutura;
Apresentao;
Indicao de mudanas.

Estilo de Escrita

O estilo do escritor crucial para a qualidade da documentao.

Diretrizes:
Correo gramatical;
Sentenas e pargrafos curtos;
Conciso;
Preciso;
Repetio de conceitos complexos;
Sees, sub-sees, e listas.

Reviso - Pontos Principais

Documentao tem vrios usos tcnicos e gerenciais.

Documentao pode ser de processo ou de produto.

Qualidade da documentao depende de:

Planejamento;
Padronizao;
Medidas de qualidade;
Estilo de escrita.

Responda
1.) A documentao de um sistema pode ser dividido em dois
grandes grupos? Quais so eles? D exemplos?

2.) Qual o profissional responsvel pela Documentao de um

Sistema?
3.) Qual a importncia de se documentar um Sistema?
4.) Qual a diferena entre Processo e Produto ?
5.) Cite com exemplos alguns erros na documentao de cdigos
de um Sistema?
6.) Quais so os aspectos mais importantes para se conseguir
produzir bons documentos de um Sistema?
7) Levantar principais processos do sistema Aluno online.

Engenharia de Software
II
Introduo a Documentao
De
Software
???? DVIDAS ???