Documentação de Software
Alexandre Vasconcelos ([email protected])
© 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
É 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
System
evaluators
Functional
description
Description of
services
System
administrators
Novice
users
Experienced
users
System
administrators
Installation
document
Introductory
manual
Reference
manual
Administrator’s
guide
How to install
the system
Getting
started
Facility
description
Operation and
maintenance
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
 Comentários
visual
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
 A existência
(ou projeto) dos documentos
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!