Preview only show first 10 pages with watermark. For full document please download

Engenharia De Software - Aula 12

Engenharia de software Luís A. Alexandre UBI, 25 de Fevereiro de 2008

   EMBED


Share

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