Transcript
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Engenharia de software Lu´ıs A. Alexandre
UBI, 2 de Junho de 2008
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Conte´udo
I
Documenta¸c˜ao de software
I
Qualidade da documenta¸c˜ao
I
Documenta¸c˜ao on-line
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao de software I
A documenta¸c˜ao de software pode ser dividida em v´arias componentes de acordo com a seguinte figura: Documentação
Processo
Produto
Utilizador
I
Sistema
A documenta¸c˜ao ´e normalmente produzida pelos engenheiros de software que desenvolvem o sistema embora alguma da documenta¸c˜ao que ´e tornada p´ ublica possa ser editada e corrigida por escritores t´ecnicos. Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Finalidade da documenta¸c˜ao
I
Os documentos associados a um projecto de software servem v´arios fins: I
I
I
I
S˜ao um meio de comunica¸c˜ao entre membros da equipa de desenvolvimento; S˜ao um reposit´ orio de informa¸c˜ao para os engenheiros de manuten¸c˜ao; Fornecem informa¸c˜ao `a gest˜ao para ajudar a planear, atribuir or¸camento e calendarizar o processo de desenvolvimento; Explicam aos utilizadores como usar e administrar o sistema.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do processo e do produto I
I
I
I
A documenta¸c˜ao do processo refere-se aos documentos que dizem respeito ao processo de desenvolvimento: calend´arios, standards, actas de reuni˜ oes, etc. A documenta¸c˜ao do processo ´e produzida durante o processo de desenvolvimento para auxiliar a sua gest˜ao. A documenta¸c˜ao relativa ao produto inclui descri¸c˜oes do sistema para consumo dos pr´ oprios engenheiros e a documenta¸c˜ao que ser´a entregue aos utilizadores. A documenta¸c˜ao do produto ´e maioritariamente usada ap´os o sistema ter sido desenvolvido, embora tenha documentos usados no processo de desenvolvimento (p. ex., o documento com os requisitos). Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do processo I
Para ser poss´ıvel a gest˜ao do software ´e necess´ario tornar o processo vis´ıvel: ´e dif´ıcil gerir algo que n˜ao se pode tocar ou visualizar facilmente como o software.
I
Uma forma de tornar o processo vis´ıvel ´e usando documenta¸c˜ao. Existem v´arios tipos de documenta¸c˜ao associados ao processo:
I
I
I
I
Planos, estimativas e calend´arios: s˜ao produzidos pela gest˜ao e s˜ao usados para controlar o desenrolar do processo; Relat´ orios: documentos relativos `a utiliza¸c˜ao de recursos usados no desenvolvimento; Standards (padr˜ oes): documentos que especificam como ´e que o processo deve ser implementado. Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do processo (cont.) I
I
I
Documentos de trabalho: guardam ideias, vers˜oes internas da documenta¸c˜ao do produto, descrevem estrat´egias de implementa¸c˜ao e problemas encontrados. Memorandos e emails: contˆem detalhes de comunica¸c˜ao di´aria entre a gest˜ao e os engenheiros de desenvolvimento.
I
Uma caracter´ıstica da documenta¸c˜ao do processo ´e a sua r´apida desactualiza¸c˜ao: normalmente cont´em informa¸c˜ao relativa a ac¸c˜oes di´arias ou semanais.
I
A maioria da documenta¸c˜ao do processo ´e descartada ap´os a entrega do sistema.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do produto
I
Descreve o produto.
I
Tem, ao contr´ario da documenta¸c˜ao do processo, um tempo de vida u ´til longo. Pode dividir-se em dois tipos:
I
I
I
documenta¸c˜ao para o utilizador: usada pelos utilizadores (explica como usar e quais as caracter´ısticas do produto); documenta¸c˜ao do sistema: usada pelos engenheiros de manuten¸c˜ao.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do utilizador
I
Existem cinco documentos que podem ser fornecidos aos utilizadores, dependendo do seu perfil: I I I I I
Descri¸c˜ao funcional Manual de instala¸c˜ao Manual de utilizador Manual de referˆencia Manual de administra¸c˜ao
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do utilizador (cont.) I
A descri¸c˜ao funcional d´a uma ideia dos requisitos do sistema e uma descri¸c˜ao dos servi¸cos que o sistema fornece. A ideia ´e um utilizador poder ler a descri¸c˜ao funcional para decidir se este ´e o sistema que ele procura.
I
O manual de instala¸c˜ao permite que um administrador do sistema proceda `a sua instala¸c˜ao. Deve descrever o tipo de hardware necess´ario, que ficheiros de configura¸c˜ao s˜ao necess´arios, como arrancar com o sistema, como efectuar a interliga¸c˜ao a outros j´a existentes. Muitos programas vˆem com um instalador autom´atico que evita a necessidade de um manual de instala¸c˜ao. Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do utilizador (cont.)
I
O manual de utilizador deve descrever a sua utiliza¸c˜ao normal, como aceder `as funcionalidades b´asicas e deve ser ilustrado com exemplos, incluindo, tipicamente, capturas de ecr˜a.
I
O manual de referˆencia deve descrever todas as ´ um documento exaustivo, funcionalidades do sistema. E muitas vezes de dif´ıcil leitura. No entanto n˜ao ´e escrito para uma leitura sequencial, mas sim para ser consultado pontualmente.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do utilizador (cont.)
I
O manual de administra¸c˜ao ´e necess´ario apenas para alguns tipos de sistema. Descreve as mensagens geradas pela interac¸c˜ao do sistema com outros sistemas, como fazer manuten¸c˜ao do sistema (inclusive ao n´ıvel do hardware), como efectuar liga¸c˜oes do sistema a novos perif´ericos, como gerir diferentes perfis ou utilizadores, etc.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao Documenta¸c˜ ao
de do do do do do
software processo e do produto processo produto utilizador sistema
Documenta¸c˜ao do sistema I I
Esta documenta¸c˜ao consiste em documentos que descrevem os requisitos, o desenho, a implementa¸c˜ao e os testes do sistema. Para grandes sistemas, deve incluir: I I I I
I I
I
O documento com a an´alise de requisitos; Um documento que descreva a arquitectura do sistema; A descri¸c˜ao de cada programa que comp˜ oe o sistema; A descri¸c˜ao da funcionalidade e do interface de cada componente do sistema; O c´ odigo fonte documentado; Documentos de valida¸c˜ao que descrevam os testes efectuados e os resultados obtidos; Um guia para a manuten¸c˜ao do sistema que descreva problemas do sistema conhecidos e como a evolu¸c˜ao do sistema foi planeada aquando do seu desenho. Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Estrutura da documenta¸c˜ ao Estilo de escrita
Estrutura da documenta¸c˜ao
I
A estrutura de um documento tem um grande impacto na facilidade de leitura e na sua utiliza¸c˜ao.
I
Uma estrutura correcta facilita a pesquisa de informa¸c˜ao no documento.
I
Um documento bem estruturado permite que sejam lidas apenas determinadas por¸c˜ oes (as de interesse para o utilizador) sem ser necess´ario o recurso a muitas referˆencias.
I
Um texto com poucas auto-referˆencias ´e de mais f´acil manuten¸c˜ao.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Estrutura da documenta¸c˜ ao Estilo de escrita
Estrutura da documenta¸c˜ao (cont.) I
Algumas caracter´ısticas estruturais que devem existir num documento: I
I
I
I
Capa que contenha: t´ıtulo do documento, autor, data, tipo de documento. Documentos com mais de meia d´ uzia de p´aginas devem ser divididos em cap´ıtulos, sec¸c˜ oes e eventualmente, sub-sec¸c˜oes. Um documento que contenha informa¸c˜ao detalhada deve conter um ´ındice. Um ´ındice pode tornar utiliz´avel mesmo um documento mal redigido. Se o p´ ublico alvo do documento tiver diferentes vocabul´arios deve ser inclu´ıdo um gloss´ario.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Estrutura da documenta¸c˜ ao Estilo de escrita
Estilo de escrita I
I
Um documento deve ser escrito, lido, criticado e reescrito, se poss´ıvel por mais que uma pessoa. Aqui ficam alguns pontos a ter em conta aquando da redac¸c˜ao de um documento t´ecnico: I
I I I
I
Um documento t´ecnico tem, como qualquer outro, de estar correctamente escrito em termos de sintaxe e gramaticais; N˜ao usar frases longas que apresentem diferentes ideias; Manter os par´agrafos curtos: n˜ao mais de 7 frases. N˜ao ”encher”: se ´e poss´ıvel dizer o que se pretende em poucas palavras, ent˜ao n˜ao deixar que o texto se alongue. Definir os termos que s˜ao usados no texto e n˜ao s˜ao do conhecimento comum; Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Estrutura da documenta¸c˜ ao Estilo de escrita
Estilo de escrita (cont.)
I
I I
I
I
Explicar mais que uma vez os pontos mais complexos; Usar a divis˜ao do texto em sec¸c˜ oes e sub-sec¸c˜oes para facilitar a compreens˜ao da estrutura do tema em discuss˜ao; Usar listas: ´e mais simples apreender factos quando est˜ao listados do que quando s˜ao inseridos numa frase; N˜ao usar apenas referˆencias num´ericas: em vez de ”na sec¸c˜ao 3” usar ”na sec¸c˜ao 3, onde foi apresentado o modelo X”.
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao on-line Desvantagens da documenta¸c˜ ao on-line
Documenta¸c˜ao on-line I
Este tipo de documenta¸c˜ao vai desde o simples ficheiro readme.txt at´ e `a documenta¸c˜ao on-line que usa hiperliga¸c˜oes e ´e sens´ıvel ao contexto.
I
A principal vantagem da documenta¸c˜ao on-line ´e a sua acessibilidade: n˜ao ´e necess´ario ir buscar o manual e folhe´a-lo para encontrar o que procuramos.
I
Outra grande vantagem ´e a possibilidade de efectuar pesquisas por palavras ou frases.
I
No entanto, a documenta¸c˜ao on-line deve ser complementar `a impressa pois apresenta algumas desvantagens, como veremos de seguida. Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Documenta¸c˜ ao on-line Desvantagens da documenta¸c˜ ao on-line
Desvantagens da documenta¸c˜ao on-line
I
Impossibilidade de folhear (dar uma vista de olhos) para ficar com uma no¸c˜ao da extens˜ao e detalhe da documenta¸c˜ao.
I
A leitura de grandes por¸c˜ oes de texto on-line ´e mais cansativa que a leitura sobre papel. ´ f´acil ficar perdido num sistema de documenta¸c˜ao on-line e E n˜ao saber por onde continuar ou que parte da documenta¸c˜ao j´a foi consultada.
I
Lu´ıs A. Alexandre
Engenharia de software
Documenta¸c˜ ao de software Qualidade da documenta¸c˜ ao Documenta¸c˜ ao on-line Conclus˜ ao
Leituras complementares
Leituras complementares
I
”Software documentation”, I. Sommerville, 2001 (paper no site da disciplina)
Lu´ıs A. Alexandre
Engenharia de software