1

Documentação de Software

Simone Vasconcelos

2

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

3

Usos da DocumentaçãoMeio 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.

4

Tipos de DocumentaçãoDocumentação do processo! É produzida para que o processo de

desenvolvimento do software seja administrável! Registram os processos de desenvolvimento e

manutenção do softwareDocumentaçã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

5

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 softwarePadrões! Estabelecem como o processo deve ser

implementado! Podem ser organizacionais, nacionais, ou

internacionais

6

Documentação do Processo -Categorias

Memorandos, comunicações, mensagens eletrônicas! Registram as comunicações entre gerentes e

engenheiros de softwareDocumentos 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.

7

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.

8

Documentação do UsuárioDeve 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.

9

Documentação do UsuárioDescriçã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

10

Documentação do UsuárioManual 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 utilizadasDocumento de instalação! Descreve como instalar o sistema ! Especifica a plataforma mínima necessária à sua

instalação

11

Documentação do Usuário Manual do administrador do sistema.! Informações relevantes para uma boa

administração do sistemaManual 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

12

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 comoverviews levando a especificações mais detalhadas e formais de cada aspecto do sistema.

13

Documentação do Sistema Documento de requisitosDescrição da arquitetura do sistemaDescrição da arquitetura de cada um dos programasListagens do código fonte dos programas Documentos de validação, descrevendo! Como cada programa é validado! Como estas informações se relacionam com os

requisitosGuia de manutenção! Problemas já identificados! Partes do sistema que são dependentes do hardware

e software utilizados

14

Documentação do Código Pode ser extremamente útil para melhorar (facilitar) o entendimento dos programas:

! Escolha de nomes;

! Organização visual;

! Comentários.

15

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.

16

Organização VisualManeira 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.

17

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.

18

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.

19

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.

20

Comentários FuncionaisEncontram-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.

21

Qualidade dos DocumentosA 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.

22

Padrão do Processo de Documentação

Procedimentos de desenvolvimento:

! Ferramentas;

! Procedimentos de qualidade.

Flexíveis para lidar com todos os tipos

de documentos;

23

Padrão de Documentação

Aplicam-se a todos os documentos (de um projeto)! Identificação;

! Estrutura;

! Apresentação;

! Indicação de mudanças.

24

Estilo de EscritaO 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.

25

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.