aula 1- introdução a documentação
DESCRIPTION
Introdução a engenharia de software.TRANSCRIPT
Engenharia de Software II
Introdução a Documentação
de Software
e
Padrões Utilizados nas
Documentações
A Documentação de Software
Necessidade ou preciosismo?
A documentação de software, mesmo sendo o carma de qualquer desenvolvedor, é extremamente necessária e auxilia na redução de horas preciosas na correção de problemas.
Para muitos desenvolvedores, a criação de documentação técnica é a parte mais aterrorizante para se enfrentar em todo o processo de criação de um software.
Necessidade de escrever várias e várias páginas de texto, gráficos e desenhos.
Vídeo: levantamento de requisitos
Documentação, o que é?
A documentação de um software é composta por várias partes
diferentes que abrangem todo o sistema e pode ser dividida em dois
grandes grupos: documentação técnica e documentação de uso.
Técnica é voltada ao desenvolvedor ou pessoa de TI e compreende
principalmente dicionários e modelos de dados, fluxogramas de
processos e regras de negócios, dicionários de funções e comentários
de código.
De uso é voltada tanto para o usuário 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
informações que se deseja.
Ambas podem ser criadas em formatos de visualização como: páginas HTML,
documentos PDF, apresentações, vídeos ou ainda arquivos texto.
Contexto da Documentação
Qualquer software deve ter uma quantidade razoável de
documentação.
Documentos de trabalho.
Manuais de usuário produzidos profissionalmente.
Em geral, a maioria destes documentos é produzida por engenheiros
de software.
Uma parte considerável dos custos de um projeto pode ser gasta com
documentação.
documentação é tão importante (ou mais) que as questões de
segurança.
Usos da Documentação
Meio de comunicação entre os membros de um grupo de
desenvolvimento;
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.
Informações para as pessoas que venham a fazer manutenção no
sistema;
7
Tipos de Documentação
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
Estudo de
Caso
Processos
8
Processos (verificar o contexto, neste caso estamos falando dos processos de
um software (produto))
Cadastrar hotéis
Efetuar reserva
Cadastrar clientes
Cadastrar acomodações
Cadastrar usuário
Gerenciar reserva
Estudo de Caso
Documentação do Processo
Processo de Software:
Enfoca os processos de software,
os elementos que compõem um processo,
a definição de processos para projetos,
modelos de processo,
normas e modelos de qualidade de processo de software
e a automatização do processo de software.
“O processo de software pode ser definido como um conjunto de atividades, métodos, práticas, e transformações que as pessoas empregam para desenvolver e manter software e os produtos associados (ex. planos de projeto, documentos de projeto (design), código, casos de teste, e manual do usuário)”.[PAULK95]
Um processo de software é o que define quais atividades devem ser realizadas dentro de uma produção de sistemas, define também as pessoas envolvidas e os artefatos a serem gerados. Já o modelo de processo de software define a sequência com que as atividades são executadas e quais as pessoas estão envolvidas e quais os artefatos são gerados por cada atividade.
Documentação do Processo
12
Documentação do Processo - Categorias
Planos, estimativas, e cronogramas
Produzidos por gerentes
Usados para prever e controlar o processo.
Relatórios
Descrevem como os recursos foram utilizados durante o
desenvolvimento do software
Padrões
Estabelecem como o processo deve ser implementado
Podem ser organizacionais, nacionais, ou internacionais
13
Documentação do Processo - Categorias
Memorandos, comunicações, mensagens eletrônicas
Registram as comunicações entre gerentes e engenheiros de
software
Documentos técnicos de trabalho
Registram as idéias e pensamentos dos engenheiros de
software.
Descrevem estratégias de implementação.
Registram problemas já identificados.
Especificam as razões para as decisões de projeto.
14
Documentação do Produto
Descreve o software produzido.
Tem vida longa e deve estar sempre atualizada em relação ao
código.
Divide-se em:
Documentação do sistema.
Documentação do usuário.
Deve levar em conta os diversos tipos de usuários.
Exemplo:
Usuários finais
Usam o software para auxiliá-los em alguma tarefa
Não estão interessados em detalhes técnicos ou administrativos.
Administradores do sistema
Responsáveis pela administração do software
Ex: operadores, gerentes de rede, etc.
Documentação do Produto
- Documento do Usuário
Descrição funcional do sistema
Requisitos gerais do sistema
Serviços fornecidos por ele
Manual de introdução
Apresenta uma introdução informal do sistema e descreve seu
uso normal
Deve explicar como começar a usar o sistema e como os
usuários podem utilizar as facilidades oferecidas pelo sistema
Documentação do Produto
- Documento do Usuário
Manual de referência
Informações concisas das principais funções 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 técnicas de descrição formal podem ser
utilizadas
Documento de instalação
Descreve como instalar o sistema
Especifica a plataforma mínima necessária à sua instalação
Documentação do Usuário
.Manual do administrador do sistema.
.Informações relevantes para uma boa administração
do
sistema
.Ajuda on-line
Documentação do Usuário
Description
ofservicesFunctionaldescriptionSystemevaluatorsHow
to installthe
systemInstallationdocumentSystemadministratorsGetti
ngstartedIntroductorymanualNoviceusersFacilitydescri
ptionReferencemanualExpeiencedusersOperation
andmaintenanceAdministrator’sguideSystemadministr
ators
Documentação do Sistema
.Descreve a implementação do sistema, desde a
especificação dos requisitos até o plano de testes
.É importante que seja estruturada com
overviewslevando a especificações mais detalhadas e
formais de
cada aspecto do sistema
.Infelizmente, a manutenção da documentação
atualizada é freqüentemente negligenciada.
Documentação do Produto
- Documento do Usuário
Manual do administrador do sistema.
Informações relevantes para uma boa administração do
sistema
Ajuda on-line
Documentação do Produto
- Documento do Usuário
Documentação do Produto
- Documento do Sistema
Descreve a implementação do sistema, desde a
especificação dos requisitos até o plano de testes.
É importante que seja estruturada com overviews
levando a especificações mais detalhadas e formais de
cada aspecto do sistema.
Documentação do Produto
- Documento do Sistema
Documento de requisitos
Descrição da arquitetura do sistema
Descrição da arquitetura de cada um dos programas
Listagens do código fonte dos programas
Documentos de validação, descrevendo
Como cada programa é validado
Como estas informações se relacionam com os requisitos
Guia de manutenção
Problemas já identificados
Partes do sistema que são dependentes do hardware e
software utilizados
21
Documentação do Código
Pode ser extremamente útil para melhorar (facilitar) o
entendimento dos programas:
Escolha de nomes;
Organização visual;
Comentários.
Documentação do Código
- Escolha de Nomes
Os nomes devem ser significativos em relação ao que eles
representam.
Identificadores maiores melhoram a compreensão dos programas,
mesmo em programas pequenos.
Identificadores grandes demais dificultam sua digitação e podem
se tornar uma fonte de erros.
Documentação do Código
- Organização Visual
Maneira como o código aparece na tela do computador ou em
uma listagem.
Os padrões de boa codificação mais aceitos incluem:
Um único comando por linha;
Espaçamento entre os componentes dos comandos;
Identação.
Documentação do Código
- Comentários
Devem ser usados para explicar o que o software faz, ao invés de
como ele faz.
Duas formas de comentários são mais comuns:
Comentários em forma de prólogo;
Comentários funcionais.
Documentação do Código
- Comentários em Forma de Prólogo
Aparecem no início de cada módulo.
Formato:
Declaração de propósitos;
Descrição da interface com outros módulos:
Forma de uso;
Quais os módulos subordinados;
etc.
Pequena descrição dos dados, variáveis, limitações de uso, e
quaisquer outras informações que sejam importantes.
Documentação do Código
- Comentários em Forma de Prólogo
Histórico do seu desenvolvimento
O nome do autor.
A data em que foi criado.
Para cada uma das modificações feitas no módulo:
O nome do revisor;
A data de alteração;
Uma descrição da alteração.
Documentação do Código
- Comentários Funcionais
Encontram-se embutidos no código fonte.
Descrevem as funções de processamento.
Devem fornecer algo a mais do que simplesmente parafrasear o
código.
Bons comentários:
Descrevem blocos de código ao invés de comentar cada uma
das linhas.
Usam linhas em branco e identação para que o texto dos
comentários seja facilmente identificável.
São corretos.
28
Exercícios
Exemplo de trecho de algoritmo mal escrito.
soma ← 0;
i ← 1;
enquanto i < 18 faça
soma ← soma + i;
i ← i +1;
fimenquanto
escreva (soma);
29
Exercícios
Exemplo de trecho de algoritmo mal escrito.
soma ← 0; { atribui o valor 0 à variável soma}
i ← 1; { atribui o valor 1 à variável i }
enquanto i < 18 faça{enquanto i não 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 }
30
Exercícios Exemplo de trecho de algoritmo bem escrito.
{ faz a soma dos números inteiros de 1 a 18 }
{ Autor: Viviane data: 12/02/2010}
soma ← 0; { é o somatório }
i ← 1; { número inteiro gerado }
enquanto i < 18 faça{ gera os número inteiros e calcula o somatório }
soma ← soma + i;
i ← i +1;
fimenquanto
escreva (soma);
Qualidade dos Documentos
A qualidade da documentação é tão importante quanto a
qualidade do código.
Aspectos importantes para se conseguir produzir bons
documentos incluem:
Planejamento (ou projeto) dos documentos;
A existência de padrões a serem seguidos;
Procedimentos de garantia de qualidade.
Padrão do Processo de
Documentação
Procedimentos de desenvolvimento:
Ferramentas;
Procedimentos de qualidade.
Flexíveis para lidar com todos os tipos de documentos;
Padrão de Documentação
Aplicam-se a todos os documentos (de um projeto)
Identificação;
Estrutura;
Apresentação;
Indicação de mudanças.
Estilo de Escrita
O estilo do escritor é crucial para a qualidade da documentação.
Diretrizes:
Correção gramatical;
Sentenças e parágrafos curtos;
Concisão;
Precisão;
Repetição de conceitos complexos;
Seções, sub-seções, e listas.
Revisão - Pontos Principais
Documentação tem vários usos técnicos e gerenciais.
Documentação pode ser de processo ou de produto.
Qualidade da documentação depende de:
Planejamento;
Padronização;
Medidas de qualidade;
Estilo de escrita.
Responda
1.) A documentação de um sistema pode ser dividido em dois grandes grupos? Quais são eles? Dê exemplos?
2.) Qual é o profissional responsável pela Documentação de um Sistema?
3.) Qual a importância de se documentar um Sistema?
4.) Qual a diferença entre Processo e Produto ?
5.) Cite com exemplos alguns erros na documentação de códigos de um Sistema?
6.) Quais são 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
Introdução a Documentação
De
Software
???? DÚVIDAS ???