CURSO: CET/DSAS DISCIPLINA: Eng.

de Software ANO LECTIVO: 2009/2011

CET/DSAS {EngSoft}
Joel Carvalho - 14.10.2010 Captulo 5
Documentao de Software

FORMAO TECNOLGICA

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Sntese
i. Objectivos e Componentes da Documentao ii. Qualidade da Documentao iii.Documentao on-line.

FORMAO TECNOLGICA

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Objectivos e Componentes da Documentao

Mod.AFTEBI.P-052.rev02

i.

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Componentes
A documentao de software pode ser dvida na seguintes componentes: Processo Produto Utilizador Sistema A documentao normalmente produzida pelos engenheiros de software que desenvolveram o sistema, embora ela possa e deva ser revista por escritores tcnicos.
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Objectivos
Os documentos produzidos no processo de engenharia de software cumprem os seguintes fins: Meio de comunicao entre membros da equipa de desenvolvimento. Repositrio de informao para os engenheiros de manuteno. Ajudam no estabelecimento de oramentos e calendrios para o processo de desenvolvimento. Ajudam os utilizadores a utilizar e administrar o sistema.
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Doc. de Processo e Produto

A documentao de processo diz respeito aos documentos do processo de desenvolvimento: calendrios, mapas, standards, actas de reunies, etc. A documentao do processo produzida durante o prprio processo de desenvolvimento e permite a gesto do mesmo. Por sua vez a documentao de produto inclu descries do sistema para os prprios engenheiros bem como para os utilizadores finais do software. Esta documentao utilizada maioritariamente aps o processo de desenvolvimento no entanto ela faz parte integrante do mesmo.

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Tipos de Doc. De Produto

Existem cinco tipos de documentos que podem ser fornecidos aos utilizadores dependendo do seu perfil. Descrio Funcional Manual de Instalao Manual de Utilizador Manual de Referncia Manual de Administrao
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Descrio Funcional
Esta descrio apresenta os requisitos do sistema e faz uma descrio dos servios que o sistema fornece. Esta descrio deve ser facultada ao cliente para ele decidir se o software cumpre com o pretendido. Esta descrio pode ser feita totalmente por texto, pode incluir diagramas, tabelas, etc.

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Manual de Instalao
Este manual permite que um administrador do sistema possa instalar o software produzido sem grandes dificuldades. O documento deve descrever o tipo de hardware necessrio, quais os ficheiros de configurao (caso existam) e como devem ser manipulados, como proceder interligao desse software com outros (caso necessrio). Hoje em dia, a maioria dos programas so fornecidos com um instalador automtico que evita a necessidade de um manual de instalao sofisticado.
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Manual de Utilizador
O manual de utilizador deve descrever a utilizao normal do software. Por exemplo deve descrever/demonstrar como aceder a determinadas funcionalidades e preferencialmente deve usar abundantemente ilustraes (imagens ou screenshots). Este manual pode ser dividido pelos diferentes perfis de utilizador podendo, ou no, originar vrios documentos dedicados a cada perfil.
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Qualidade da Documentao
Mod.AFTEBI.P-052.rev02

ii.

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Estrutura
A estrutura dos documentos tem um grande impacto na facilidade de leitura dos mesmos e na sua espontnea utilizao. Uma boa estrutura, com um ndice descritivo permite um rpido e eficiente acesso informao, sem obrigao da leitura integral do documento. Quanto mais referencias externas tiver o documento pior ser de leitura. Um bom documento um documento autocontido com a estrutura adeqauda.
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Estrutura
De seguida so apresentadas algumas caractersticas para a construo de um bom documento: Capa com: Ttulo, autor, data, tipo de documento. Documentos com mais de meia dzia de pginas devem ser divididos por captulos, seces e eventualmente subseces. Documentos extensos e/ou com informao detalhada, devem conter um ndice. Se o pblico alvo no dominar todos os termos usados deve ser utilizado um glossrio com a definio desses termos.

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Estilo de Escrita
Um documento deve sempre ser visto e revisto por quem o escreveu e revisto pelo menos uma vez por quem nunca viu o documento previamente. Aspectos tcnicos a ter em considerao:
Utilizar correctamente o idioma do documento, quer em termos de sintaxe como em termos gramaticais. No usar frases com mais de duas linhas. Pargrafos com menos de 8 frases. Evitar redundncia/repetio e ir directo ao assunto. Identificar e definir os termos que o leitor pode no conhecer. Escrever na terceira pessoa (escrevemos => escreve-se). Sempre que for feito uma referencia no Utilizar apenas a referencia numrica
Mod.AFTEBI.P-052.rev02

Utilizar listas em vez de textos extensos.

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Documentao on-line

iii.

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Documentao on-line
Este tipo de documentao vai desde o simples ficheiro readme.txt at documentao html automaticamente gerada por programas como o doxygen. No caso da documentao html, existem sempre hiperligaes para vrios contextos, como por exemplo do nome da classe para os atributos da mesma, para as operaes, etc. A principal vantagem deste tipo de documentao foca-se na usabilidade, no fcil acesso informao, mas por vezes tornam-se confusas e demasiado sofisticadas.

Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Perguntas?
{Bom Trabalho!}
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

O que entende por documentao? D um exemplo de ferramentas de produo automatizada de documentao de cdigo. Enumere trs regras para a produo de um bom documento. Qual a diferena entre a documentao de processo e a documentao de sistema? O que entende por manual de utilizador e manual de instalao. O que entende por descrio funcional.
Mod.AFTEBI.P-052.rev02

CURSO: CET/DSAS DISCIPLINA: Eng. de Software ANO LECTIVO: 2009/2011

Ipsa scientia potestas est

{O saber poder}

FORMAO TECNOLGICA

Mod.AFTEBI.P-052.rev02