Este documento discute a importância da documentação de software, seus usos e tipos principais. A documentação pode ser de processo ou produto, e ambas são essenciais para a comunicação, manutenção e uso do software. Uma boa documentação requer planejamento, padronização e qualidade na escrita para ser efetiva.

1. Documentação de Software
Simone Vasconcelos
1

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

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

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

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 software
Padrões
! Estabelecem como o processo deve ser
implementado
! Podem ser organizacionais, nacionais, ou
internacionais
5

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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;
22

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

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

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