Documentação de SoftwareDocumentação de Software

Alexandre Vasconcelos (amlv@cin.ufpe.br)

© 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!