Titulo Estágio
A melhoria da relação custo-beneficio na escrita de documentação
Áreas de especialidade
Engenharia de Software
Local do Estágio
SSE - CISUC - DEI
Enquadramento
O trabalho proposto foca-se nas problemáticas associadas à escrita e manutenção de documentação técnica no decorrer do processo de desenvolvimento de software. Embora seja uma necessidade universalmente aceite por academia e indústria, é frequentemente descorada ou ignorada completamente. Fundamentalmente existe um sentimento geral nos programadores de software que o valor retirado da escrita e subsequente manutenção da documentação não compensa o esforço investido.
Sobre o valor percecionado, este advém de não ser o autor quem retira maiores benefícios da documentação escrita. Habitualmente são actores não familiarizados com a solução e o código que retiram maior valor da documentação. É portanto importante melhorar o valor extraído pelo programador de software da documentação que escreve.
Acerca do esforço investido, é necessário melhorar os métodos e ferramentas utilizados na escrita de documentação para reduzir o esforço percepcionado na escrita e manutenção da documentação. É especialmente difícil saber que artefacto de documentação necessita atualização no momento de modificação de certa parte do repositório de código e vice-versa.
Esta problemática associada à documentação é mais intensamente sentida em organizações de grande dimensão e com soluções desenvolvidas ao longo de vários anos. À medida que o número de pessoas envolvidas na solução aumenta e/ou há rotatividade dos actores envolvidos, a necessidade de documentação aumenta dado o seu papel como meio de comunicação eficiente e assíncrono. O problema é particularmente grave nestas organizações, dado que a não resolução do mesmo implica mecanismos de comunicação menos eficientes, pior coordenação entre os actores envolvidos no processo de desenvolvimento de software e como consequência uma solução final de pior qualidade e mais dispendiosa.
A documentação técnica de software é uma prática tão antiga como a prática do desenvolvimento de software em si e consequentemente diversos standards, ferramentas e abordagens foram propostas ao longo dos anos. No entanto, esta proposta pretende explorar o que foi identificado como uma lacuna no espaço e prática existentes, mais precisamente nas ferramentas ao dispor da indústria.
A maioria das ferramentas disponíveis atualmente focam na solução da escrita e manutenção da documentação técnica mas fazem-no sem ligação ou com fraca interoperabilidade com o resto das ferramentas usadas no processo de desenvolvimento de software. Este facto leva a ineficiências e elevados custos na atualização da documentação. A ferramenta IcePanel faz uma tentativa nesta direção permitindo a rastreabilidade de componentes da arquitetura (modelados usando o standard C4) para artefactos e commits no GIT.
Outro aspecto está na forma como a maioria das ferramentas são disponibilizadas, em formato plataforma online e proprietária, onde a documentação e dados associados são mantidos sobre um versionamento proprietário. Nestas plataformas o utilizador perde o controlo dos seus dados e vê opções de migração limitadas. Um exemplo é a ferramenta Enterprise Architect, excelente nas suas capacidades de modelação e rastreabilidade mas limitativa no armazenamento dos dados como bases de dados de formato proprietário. Outro caso é a ferramenta Aplas que permite a indexação e rastreabilidade de metadados de várias fontes mas completamente limitada na sua disponibilização dos dados como plataforma online.
No âmbito da geração automática de documentação técnica encontram-se diversas abordagens que utilizam informação de run-time como dados de tracing (invocação entre serviços, componentes, funções) para fazer a engenharia reversa da arquitectura da solução. Para além de estarem dependentes da quantidade e resolução dos dados de tracing disponíveis, estas ferramentas têm a desvantagem das arquiteturas geradas estarem limitadas a um nível baixo de abstração e não conseguirem refletir aspectos de alto nível da solução ou negócio. A ferramenta Archium é um exemplo.
Objetivo
A dissertação tem como principal objetivo estudar como melhorar a relação custo-benefício da criação e manutenção da documentação técnica no decorrer do processo de desenvolvimento de software. Mais precisamente foca-se em 3 pontos:
- Melhorar o valor percepcionado para quem escreve documentação técnica;
- Redução do custo do processo de criação da documentação técnica;
- Redução do custo do processo de manutenção da documentação técnica.
Com vista a endereçar estes 3 pontos, a dissertação propõe a investigação, desenho e prototipagem de uma solução que permita:
- Desenho e especificação de um standard para coleção de elementos e dependências dos vários artefactos do repositório de código.
- Desenho e desenvolvimento de um sistema que permita a correspondência entre código e artefactos de documentação.
- Com base na correspondência criada, o sistema deve:
- Permitir a navegação entre os diferentes artefactos.
- Após uma modificação feita, permitir perceber potenciais atualizações necessárias a outros artefactos.
Como consequência desta dissertação espera-se a criação de um standard para a traceabilidade entre os vários artefactos criados no processo de desenvolvimento de software, mais precisamente entre artefactos de documentação e código. Espera-se ainda o desenvolvimento de uma prova de conceito do standard criado e publicação aberta do mesmo.
Para além disto é ainda esperada a escrita de um artigo científico expositivo da abordagem, standard e prova de conceito desenvolvidos.
Plano de Trabalhos - Semestre 1
A dissertação irá ser realizada durante o 2º semestre do ano lectivo 2022/2023 e o 1º semestre do ano lectivo 2023/2024. O trabalho será organizado nas seguintes fases:
1. Definição do âmbito sobre investigação
2. Estado da arte
3. Metodologia e abordagem
4. Implementação de prova de conceito
5. Relatório intermédio - até 10 de Julho de 2023
Plano de Trabalhos - Semestre 2
6. Preparação do ambiente experimental
7. Implementação e avaliação das estratégias propostas
8. Relatório final - até 15 de Janeiro de 2024
Condições
O estágio será realizado nos laboratórios do CISUC e integrado nos trabalhos do SSE Group.
Este estágio será co-orientado pelos docentes do DEI Bruno Cabral e Mário Zenha-Rela
Orientador
Bruno Cabral
bcabral@dei.uc.pt 📩