Upload
internet
View
105
Download
1
Embed Size (px)
Citation preview
Documentação de SoftwareDocumentação de Software
Alexandre Vasconcelos ([email protected])
© 2002, Centro de Informática
Universidade Federal de Pernambuco
ObjetivosObjetivos
Descrever o tipo de documentação que deve ser produzida no desenvolvimento de software
Dar dicas sobre estilos de escrita
TópicosTópicos
Classificação de documentos
Qualidade de documentos
Preparação de documentos
ContextoContexto 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
Usos da DocumentaçãoUsos 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
Tipos de DocumentaçãoTipos 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
Documentação do Processo - Documentação do Processo - CategoriasCategorias
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
Documentação do Processo -Documentação do Processo -CategoriasCategorias
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.
Documentação do ProdutoDocumentaçã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
Documentação do UsuárioDocumentaçã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 UsuárioDocumentaçã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
Documentação do UsuárioDocumentaçã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
Documentação do Usuário 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árioDocumentação do Usuário
Description ofservices
Functionaldescription
Systemevaluators
How to installthe system
Installationdocument
Systemadministrators
Gettingstarted
Introductorymanual
Noviceusers
Facilitydescription
Referencemanual
Experiencedusers
Operation andmaintenance
Administrator’sguide
Systemadministrators
Documentação do Sistema 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.
Documentação do Sistema 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
Documentação do Código Documentação do Código Pode ser extremamente útil para melhorar
(facilitar) o entendimento dos programas:
Escolha de nomes
Organização visual
Comentários
Escolha de NomesEscolha 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.
Organização VisualOrganizaçã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
ComentáriosComentá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
Comentários em Forma de PrólogoComentá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
Comentários em Forma de PrólogoComentá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.
Comentários FuncionaisComentá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
Qualidade dos DocumentosQualidade 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
Qualidade dos DocumentosQualidade 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
Padrão do Processo de Padrão do Processo de DocumentaçãoDocumentaçã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
Padrão de DocumentaçãoPadrã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
Estilo de EscritaEstilo 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
Pontos PrincipaisPontos 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!