Documentação de Software Simone Vasconcelos 1
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. 2
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 à 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. 3
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 4
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 5
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. 6
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. 7
Documentação do Usuário Deve levar em conta os diversos tipos de usuários É importante distinguir entre os vários 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. 8
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 9
Documentação do Usuário Manual de referência! Descreve as facilidades do sistema e seu uso! Fornece uma lista das mensagens de erro 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 10
Documentação do Usuário Manual do administrador do sistema.! Informações relevantes para uma boa administração do sistema Manual de referência rápida do sistema.! Informações concisas das principais funções do sistema e como utilizá-las! Mensagens de erros mais comuns Ajuda on-line 11
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. 12
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 13 e software utilizados
Documentação do Código Pode ser extremamente útil para melhorar (facilitar) o entendimento dos programas:! Escolha de nomes;! Organização visual;! Comentários. 14
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. 15
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;! Indentação. 16
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. 17
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. 18
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. 19
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. 20
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. 21
Padrão do Processo de Documentação Procedimentos de desenvolvimento:! Ferramentas;! Procedimentos de qualidade. Flexíveis para lidar com todos os tipos de documentos; 22
Padrão de Documentação Aplicam-se a todos os documentos (de um projeto)! Identificação;! Estrutura;! Apresentação;! Indicação de mudanças. 23
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. 24
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. 25