A apresentação está carregando. Por favor, espere

A apresentação está carregando. Por favor, espere

Documentação de Software

Apresentações semelhantes


Apresentação em tema: "Documentação de Software"— Transcrição da apresentação:

1 Documentação de Software
Alexandre Vasconcelos © 2002, Centro de Informática Universidade Federal de Pernambuco

2 Objetivos Descrever o tipo de documentação que deve ser produzida no desenvolvimento de software Dar dicas sobre estilos de escrita

3 Tópicos Classificação de documentos Qualidade de documentos
Preparação de documentos

4 Contexto 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

5 Usos da Documentação 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 para a 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

6 Tipos de Documentação Documentação do processo Documentação do produto
É 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

7 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

8 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.

9 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 usuário Documentação do sistema

10 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.

11 Documentação 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

12 Documentação 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

13 Documentação do Usuário
Manual do administrador do sistema. Informações relevantes para uma boa administração do sistema Ajuda on-line

14 Documentação do Usuário

15 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 overviews levando a especificações mais detalhadas e formais de cada aspecto do sistema Infelizmente, a manutenção da documentação atualizada é freqüentemente negligenciada.

16 Documentação 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

17 Documentação do Código
Pode ser extremamente útil para melhorar (facilitar) o entendimento dos programas: Escolha de nomes Organização visual Comentários

18 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.

19 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 Espacejamento entre os componentes dos comandos Indentação

20 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

21 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

22 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.

23 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 indentação para que o texto dos comentários seja facilmente identificável São corretos

24 Qualidade dos Documentos
A qualidade da documentação é tão importante quanto a qualidade do código. A maioria das empresas ainda não dá a necessária atenção à documentação, visando a produção de documentos bem escritos. A maioria dos documentos de sistemas de software reais são Mal-escritos Difíceis de entender Incompletos Desatualizados

25 Qualidade dos Documentos
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

26 Padrão do Processo de Documentação
Procedimentos de desenvolvimento Ferramentas Procedimentos de qualidade Flexíveis para lidar com todos os tipos de documentos Não são necessários para documentação informal

27 Padrão de Documentação
Aplicam-se a todos os documentos (de um projeto) Identificação Estrutura Apresentação Indicação de mudanças É interessante que cada empresa tenha um estilo uniforme

28 Estilo de Escrita Padrões e revisões não são suficientes
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

29 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 Produzir bons documentos não é nem fácil, nem barato!


Carregar ppt "Documentação de Software"

Apresentações semelhantes


Anúncios Google