Documentação de Software Alexandre Vasconcelos (amlv@cin.ufpe.br) © 2002, Centro de Informática Universidade Federal de Pernambuco

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

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

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

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

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

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

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.

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

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 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á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

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 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 Pode ser extremamente útil para melhorar (facilitar) o entendimento dos programas: Escolha de nomes Organização visual Comentários

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.

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

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

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

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.

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

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

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

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

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

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

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!