| Data de elaboração | 05/02/24 |
| Responsável pelo estudo |
|
| Equipe do estudo | Liderança Técnica |
| Alvo | Todos os sistemas sob a responsabilidade da Setic |
| Origem | Implementação: Estudo que levanta o que é necessário ser feito para documentar os softwares desenvolvidos pelos times de desenvolvimento da Setic, conforme a User Story: “Criar Estudo Técnico para Documentação de Sistemas: Fluxos, dependências e Arquitetura.” |
| Objetivo | Definir modelos e pontos a serem seguidos na documentação dos sistemas desenvolvidos pela Setic. |
| Observações | Sem observações |
¶ 1. Introdução
A documentação de um sistema desempenha um papel crucial no desenvolvimento, manutenção e evolução de software. Ela serve como uma fonte valiosa de informações para desenvolvedores, facilitando a compreensão da arquitetura, funcionamento interno e integrações do sistema. Além disso, a documentação fornece um guia abrangente para novos membros da equipe, permitindo uma transição mais suave e rápida no entendimento do código existente. A clareza na documentação também contribui para a eficiência operacional, uma vez que reduz a dependência excessiva de conhecimento exclusivo de alguns desenvolvedores, evitando gargalos e interrupções no processo de desenvolvimento.
Além disso, a documentação é essencial para a manutenção a longo prazo do sistema. Ela atua como um registro histórico, rastreando mudanças, atualizações e decisões de design ao longo do tempo. Isso é crucial para diagnosticar problemas, identificar melhorias e realizar atualizações de forma eficiente. Uma documentação abrangente também contribui para a transparência no desenvolvimento de software, permitindo que stakeholders compreendam melhor as funcionalidades, limitações e requisitos do sistema, promovendo uma comunicação mais eficaz e colaborativa em todo o ciclo de vida do projeto. Em resumo, a documentação é um componente indispensável para a sustentabilidade e aprimoramento contínuo de sistemas de software.
¶ 2. Desenvolvimento
¶ Mapeamento de Fluxo
É crucial compreender o fluxo de dados dentro dos sistemas, desde o início até o fim do processo, para permitir que novos desenvolvedores, que nunca tiveram contato com o sistema, se familiarizem com o produto. Para isso, utilizamos a ferramenta Miro para modelar os fluxos de um sistema. A representação visual por meio de cartões com nomes de funções específicas ou áreas do sistema, e linhas que indicam a transferência de informações de uma área para outra, facilita a compreensão do fluxo. O exemplo abaixo ilustra o fluxo de doação de aféreses no sistema Sihro:
¶ Documentação de Dependências
Documentar as dependências de um sistema é essencial para garantir uma compreensão clara de como os diferentes componentes interagem entre si e quais recursos externos são necessários para seu funcionamento adequado. Para alcançar esse objetivo, é crucial seguir alguns passos para manter as dependências do sistema documentadas:
- Liste todos os componentes do sistema, abrangendo hardware, software, bibliotecas, frameworks e serviços externos, que são necessários para o funcionamento adequado do sistema.
- Para cada componente identificado, forneça uma descrição detalhada de sua função, versão, localização (se aplicável) e integração com o sistema.
- Identifique as dependências entre os diferentes componentes do sistema. Por exemplo, se um componente A depende de um componente B para funcionar corretamente, essa relação deve ser claramente documentada.
- Se o sistema se integra com serviços externos, como APIs de terceiros ou bancos de dados hospedados na nuvem, documente essas dependências e forneça informações sobre como acessá-las, incluindo credenciais de autenticação e URLs de endpoint.
- Torne as informações acessíveis e crie uma representação visual das dependências. Recomendamos o uso do Miro para essa representação, seguindo o modelo de mapeamento de fluxo para uma compreensão mais clara e visual das interações entre os componentes do sistema.
¶ Documentação de Arquitetura
Documentar a arquitetura de um sistema é de suma importância por diversas razões. Através da documentação, é possível obter uma compreensão mais abrangente do sistema, o que facilita a sua manutenção e promove a colaboração entre os membros da equipe, especialmente ao analisar um sistema previamente documentado com o qual a equipe não teve experiência anterior. Além disso, a documentação facilita a escalabilidade, permitindo a identificação de pontos de estrangulamento e o planejamento de futuras expansões do sistema para garantir que ele possa se adaptar às necessidades em constante mudança do negócio.
Documentar a arquitetura do sistema também desempenha um papel crucial na integração de novos membros da equipe, permitindo que eles se familiarizem rapidamente com a estrutura e o funcionamento do sistema. Além disso, fornece uma base sólida para tomadas de decisão informadas sobre mudanças no sistema, permitindo que as partes interessadas avaliem o impacto das alterações propostas na arquitetura existente.
Em resumo, a documentação da arquitetura de um sistema é fundamental para garantir uma compreensão clara, manutenção eficiente, colaboração produtiva, escalabilidade, transferência de conhecimento e tomada de decisões eficazes ao longo do ciclo de vida do sistema.
Documentar a arquitetura de um sistema requer uma abordagem organizada e detalhada para capturar todas as informações relevantes sobre sua estrutura, componentes, interações e decisões de design. Aqui estão algumas etapas que podem ajudá-lo a criar uma documentação abrangente da arquitetura do sistema:
- Identificação dos Componentes: Liste todos os componentes principais do sistema, incluindo aplicativos, servidores, bancos de dados, serviços externos, interfaces de usuário e qualquer outro elemento significativo.
- Descrição de Componentes: Para cada componente identificado, forneça uma descrição detalhada de sua função, responsabilidades, interfaces (se aplicável), tecnologias utilizadas, dependências e interações com outros componentes.
- Diagramas de Arquitetura: Crie diagramas de arquitetura que ilustrem a estrutura geral do sistema, mostrando como os componentes se relacionam entre si e como as informações fluem através do sistema. Diagramas como diagramas de blocos, diagramas de camadas, diagramas de fluxo de dados e diagramas de sequência podem ser úteis para visualizar diferentes aspectos da arquitetura.
- Padrões de Design: Documente os padrões de design utilizados no sistema, explicando como eles são aplicados e os benefícios que proporcionam em termos de flexibilidade, manutenção e desempenho.
- Guia de Implantação e Configuração: Forneça instruções detalhadas sobre como implantar e configurar o sistema em diferentes ambientes, incluindo requisitos de hardware e software, procedimentos de instalação e configuração, e considerações de escalabilidade e tolerância a falhas.
¶ 3. Conclusão
Em conclusão, fica evidente que a documentação de um sistema é um elemento fundamental para o sucesso de qualquer projeto de desenvolvimento de software. Através de uma documentação abrangente e precisa, é possível garantir uma compreensão clara da arquitetura, dos componentes, das dependências e das decisões de design do sistema. Isso não apenas facilita a manutenção contínua e a evolução do sistema, mas também promove a colaboração eficaz entre os membros da equipe, facilita a integração de novos membros e fornece uma base sólida para tomada de decisões informadas. Além disso, a documentação do sistema é essencial para garantir a transferência de conhecimento e a continuidade do desenvolvimento ao longo do tempo, mesmo com mudanças na equipe ou nos requisitos do projeto. Em suma, investir tempo e esforço na documentação adequada do sistema é um investimento que traz retornos significativos em termos de eficiência, qualidade e sucesso do projeto de software.