Como documentar a Arquitetura de

Software

Veja neste artigo uma introdução sobre

como documentar os principais aspectos
técnicos relativos ao desenvolvimento de
um sistema.
por Flávio Secchieri Mariotti
Introdução
No ciclo de vida do desenvolvimento de software podemos encontrar diversas etapas e
todas com seus propósitos muito bem definidos, porém, uma que podemos dizer com
segurança ser de extrema importância é a arquitetura do software.
Quando falamos em arquitetura logo nos vem alguns padrões como Zechman
framework, TOGAF, DODAF e etc. Esses padrões existem para auxiliar e facilitar a
arquitetura corporativa no intuito de prover uma abordagem ao design, planejamento,
implementação e governança de uma arquitetura de informação corporativa.
Mas hoje em dia, com o conceito de agilidade sendo um dos principais diferenciais no
desenvolvimento de software, como implementar uma arquitetura robusta com uma
documentação simples e eficiente? Na tentativa de responder a essa pergunta, esse
artigo irá apresentar uma forma simples e eficiente para documentar a arquitetura dos
seus sistemas.
O que é Arquitetura de Software?
A arquitetura de software é uma descrição do sistema que auxilia na compreensão de
como o sistema irá se comportar.
Arquitetura é um meio de se obter uma análise antecipada para garantir que a
abordagem de design apresentada, produzirá um sistema que alcance os requisitos
exigidos pelo cliente, tais como: desempenho, segurança, disponibilidade, integridade,
flexibilidade e etc. Portanto, uma arquitetura de software consiste na definição de suas
camadas, que podem envolver entidades como: componentes de software, aplicativos
externos, sistemas legados e propriedades externas.
Por que devo documentar a arquitetura do sistema?
Segundo Steuart Henderson Britt, "Fazer negócios sem publicidade ou projetar uma
arquitetura sem documentar, é como piscar para uma garota no escuro. Você sabe que
está fazendo, mas ninguém mais sabe."
Acho essa frase engraçada, porém demonstra a verdadeira necessidade de uma
documentação. Por mais perfeita e adequada que seja sua arquitetura, será inútil para
outras pessoas que não a conhecem e que não podem entendê-la bem o suficiente para
manuseá-la. Portanto, a documentação se faz essencial para todos os casos.
Na maioria das vezes, a documentação é tratada como algo secundário, algo que as
pessoas fazem porque são obrigadas por um contrato ou gerente que a exige. Estas
podem, sim, ser razões legítimas para se documentar algo, porém, não pode faltar a
seriedade e comprometimento do arquiteto ao desenvolver esse documento, garantindo
o valor e serenidade do mesmo.
Estrutura do documento
· Histórico de revisões
· Introdução
· Visão geral
· Requisitos não-funcionais
· Mecanismos arquiteturais
· Fundamentação
· Visão de casos de uso
· Componentes
· Implantação
Entendendo sua estrutura
Nesta parte do artigo vamos entender, detalhar e ver alguns exemplos para documentar
cada fase apresentada na estrutura do documento.
1. Histórico de revisões: alguns dos principais objetivos que essa fase do documento
pretende alcançar são: deixar explícito cada alteração feita no documento; controlar a
versão do documento; deixar explícito o responsável pela alteração; controlar a
veracidade do documento.
Exemplo:
DATA VERSÃO DESCRIÇÃO AUTOR
11/12/2011 1.0 Documento inicial Flávio Mariotti
03/01/2012 1.1 Alteração no item 3 Nome do autor
2. Introdução: nesta fase do documento, o responsável deve apresentar de forma clara a
objetividade do trabalho a ser documentado. De forma sucinta, descrever do que se trata
o documento e quais assuntos serão abordados no mesmo.
3. Visão geral: a fase visão geral do documento, tem como objetivo, demonstrar de
forma sucinta, os principais elementos que compõe a arquitetura do sistema. Geralmente
essa etapa é apresentada com uma figura que deve servir como referência inicial para
qualquer entidade que tenha ou pretende entender o sistema tecnicamente.
Exemplo:

Figure 1. Imagem que representa a visão geral no documento.

4. Requisitos não-funcionais: nesta fase do documento, é necessário listar os requisitos
não funcionais encontrados no sistema, tais como: portabilidade, usabilidade,
desempenho e etc. O objetivo é colocar o nome do requisito e descrever com detalhes
suas características.
Exemplo:
Desempenho 1. A pagina principal tem que ser carregada em no máximo 3
segundos com uma conexão mínima de 256kbps.
 2. As páginas que recuperam informações de sistemas legados, devem
responder em dois segundos a cada 10.000 (contextual) em uma
conexão de 256kbps.
3. As páginas que recuperam informações de transações no banco de
dados da própria aplicação, deve responder em um segundo a cada
10.000 registros (contextual), retornados em uma conexão de 256kbps.
4. O servidor deve suportar 100.000 conexões simultâneas sem perda
de desempenho.
Interoperabilidade 1. Deve ser desenvolvido na plataforma .NET com banco de dados
SQL Server Enterprise ou Oracle 10g.
5. Mecanismos arquiteturais: nesta fase do documento, devemos listar os mecanismos
arquiteturais encontrados no sistema, ou seja, identificar todos os mecanismos de
análise, mecanismo de design e mecanismo de implementação. O intuito desta etapa é
verificar e garantir que todas as preocupações técnicas relativas à arquitetura do sistema
tenham sido capturadas.
Exemplo:
MECANISMO DE MECANISMO DE MECANISMO DE
ANÁLISE DESIGN IMPLEMENTAÇÃO
Persistência Banco de dados relacional SQL Server Enterprise
Integração com sistemas Interface utilizando XML Web Service e System.IO
legados (Cobrança) em serviço e arquivo texto.
Log Implementação dos recursos ADO.NET
de log do componente de
persistência.
Recursos avançados de Implementação de recursos Silverlight e WPF (Windows
Web 2.0 para usabilidade. Presentation Foundation).
Camada de distribuição Classe de comunicação com ADO.NET Entity
o banco, classe de
persistência.
Front-End Interface de comunicação ASP.NET, Ajax, Silverlight,
com o usuário do portal. WPF.
Tratamento de exceções Camada para tratar as ASP.NET e C#.
exceções criando interações
diferentes para usuários e
técnicos.
Build Programação da IDE para Visual Studio Team System
validação do código fonte. Foundation Server.
Deploy Configuração da IDE de Visual Studio Team System
deploy. Foundation Server.
6. Fundamentação: nesta fase, o arquiteto deve fundamentar todas as decisões
importantes de design. Além disso, deve descrever as alternativas significativas
rejeitadas no projeto. Esta seção pode indicar hipóteses, restrições, resultados de
análises e experiências significativas para a arquitetura.
7. Visão de caso de uso: esta fase, será responsável por apresentar os casos de uso ou
cenários escolhidos para a validação da arquitetura apresentada. Casos de uso, backlog,
requisitos de usuários ou qualquer outro nome que represente os itens relevantes para o
funcionamento do sistema final, o intuito é exercitar e testar os principais aspectos de
risco da arquitetura.
Exemplo:
UC Motivos da escolha
 Caso de uso 1 Descrever o motivo e os itens que serão testados.
Caso de uso 2 ...
8. Componentes: nesta fase, o arquiteto deve apresentar o diagrama de componentes. É
recomendado como boas praticas de mercado o uso do modelo UML para criação do
diagrama, que deve apresentar os possíveis componentes e suas dependências. Além
disso, o arquiteto deve criar uma tabela detalhando as responsabilidades de cada
componente.
Exemplo:

Figure 2. Representação gráfica com diagrama UML para representar os componentes.

Componente Descrição
BackOffice Descrever de forma sucinta as responsabilidades
deste componente...
Assinante
Serviço
Financeiro
Pesquisa
Suporte
Log
Segurança
9. Implantação: nesta fase, o arquiteto deve descreve as configurações de distribuição
dos componentes de software na área física em que serão implantados.
Exemplo:

Figure 3 Representação de um cenário para implantação

Conclusão
Existem diferentes maneiras e padrões para documentação da arquitetura de software,
porém, podemos concluir com esse artigo, que o importante é criar um documento que
descreve com clareza os principais aspectos envolvidos no escopo do sistema.
Além disso, podemos perceber que podemos customizar a documentação de forma que
ela se torne exequível para realidade de cada projeto. O importante é documentar com
seriedade e comprometimento com o seu trabalho.
Dicas
Para aqueles apaixonados pelo assunto, vale a pena dar uma olhada no seguinte
portal. http://www.sei.cmu.edu/architecture/
Comunicado Importante
Espero que tenham gostado do conteúdo explorado neste artigo. Caso exista qualquer
dúvida relacionada ao conteúdo ou interesse em conhecer um pouco mais sobre
Arquitetura de Software ou Documentações, informe seu interesse usando o recurso de
"comentários".
Referência
Peter Eeles; Peter Cripps. The Process of Software Architecting, Addison-Wesley
Professional, 2009.
Paul Clements; Felix Bachmann; Len Bass; David Garlan; James Ivers; Reed Little; Paulo Merson;
Robert Nord; Judith Stafford. Documenting Software Architectures: Views and Beyond,
Second Edition, Addison-Wesley Professional, 2010.

Read more: http://www.linhadecodigo.com.br/artigo/3343/como-documentar-a-arquitetura-de-

software.aspx#ixzz5B8L2AxgK