Como criar uma estrutura de documentação eficaz para seus aplicativos
PlantUML: uma ferramenta poderosa para a documentação de sistemas de informação
Amigo leitor, fico feliz em ter você novamente por aqui.
Se sinta abraçado virtualmente :)
Hoje vou escrever sobre um tema ligado a arquitetura de sistemas de informação, sobre um conjuntos de documentos muito importante, mas muitas vezes negligenciado pelos times de tecnologia, seja por falta de tempo ou prioridade mesmo.
Isso mesmo, hoje vamos falar sobre documentação e diagramas.
Introdução teórica a documentação
No Agile, por exemplo, a documentação é vista como um item de trabalho que deve ser priorizado de acordo com sua importância e necessidade para o projeto. Isso significa que a documentação pode ser simplificada e concentrada nas áreas mais importantes, ao invés de ser um documento extenso e detalhado que cobre todos os aspectos do sistema.
Além disso, o Agile também enfatiza a colaboração e o trabalho em equipe, o que pode levar a uma documentação mais colaborativa e viva, em vez de um documento estático.
Em resumo, o Agile enfatiza a entrega de valor para o cliente através de iterações curtas e adaptação contínua a mudanças, e considera a documentação como um item de trabalho que deve ser priorizado de acordo com sua importância e necessidade para o projeto.
A documentação de sistemas é importante para garantir a qualidade e manutenibilidade do sistema, mas deve ser realizada de forma equilibrada com a prioridade e disponibilidade de tempo. Uma abordagem eficiente é ter uma documentação dinâmica, detalhada e com custo de tempo zero através da automação. Dessa forma, é possível maximizar o valor da documentação tanto para os times de engenharia quanto para os demais stakeholders.
Um pouco mais sobre a documentação com a ferramenta PlantUML
Após a teoria sobre documentação em software, compartilho com vocês alguns diagramas e seus scripts correspondentes em plantuml.
@startuml
title Wikipedia Sequence Diagram
participant "User" as U
participant "Wikipedia Server" as W
U -> W: Request Wikipedia Page
W --> U: Response Wikipedia Page
opt Login
U -> W: Login Request
W --> U: Login Response
opt Edit
U -> W: Edit Request
W --> U: Edit Response
@endumlO diagrama de sequencia na primeira imagem e seu script correspondente são a representação de uma interação de usuário com o site Wikipedia, observe que mesmo simplificado, esse diagrama pode facilmente ser atualizado e modificado devido sobre tudo a sua forma escrita, se por exemplo, um rastreador de site como google analytics fosse acionado após a requisição da primeira página do site, seria necessário incluir apenas uma linha de texto para atualizar o desenho.
Nesse ponto, ao atualizarmos, teríamos a seguinte visão:
- Script plantUML correspondente a imagem
@startuml
title Wikipedia Sequence Diagram
participant "User" as U
participant "Wikipedia Server" as W
participant "Analytics" as A
U -> W: Request Wikipedia Page
W-> A: Log Visit
A --> U: Acknowledge Log Visit
W --> U: Response Wikipedia Page
opt Login
U -> W: Login Request
W --> U: Login Response
opt Edit
U -> W: Edit Request
W --> U: Edit Response
@endumlAinda sobre o plantUML, por ser uma ótima solução para representar modelos gráficos em forma textual, a estrutura se tornou muito popular graças à sua manutenibilidade e escalabilidade.
Outros motivos para adotar essa ferramenta são:
O PlantUML é de código aberto e está disponível gratuitamente, o que significa que você pode usá-lo sem ter que pagar nenhuma taxa de licenciamento ou assinatura.
O PlantUML usa algoritmos de layout inteligentes para organizar os elementos de seus diagramas de maneira clara e fácil de entender, economizando tempo e esforço de posicionar manualmente e alinhar elementos individuais.
PlantUML é um gerador, o que significa que ele cria diagramas automaticamente com base no texto que você fornece. Isso facilita a criação e atualização rápida de diagramas e permite que você se concentre em expressar a estrutura e os relacionamentos de seus diagramas, em vez de se preocupar com sua aparência.
PlantUML é altamente personalizável e fornece muitas opções para personalizar a aparência de seus diagramas. Você também pode aproveitar o conhecimento e a experiência da comunidade PlantUML para encontrar soluções para problemas comuns de layout.
Indo além, se esse script fosse gerado automaticamente através de instrumentação ou processos de testes automatizados do aplicativo o tempo para coleta e manutenção seria praticamente zero, mantendo todos os documentos que são base para tomada de decisão accessível e integro durante todo o ciclo de desenvolvimento.
Nessa linha de pensamento vou propor um exercício prático em python que demonstrará o poder da ferramenta plantUML quando utilizamos com o objetivo de automatizar documentações.
Ainda olhando para página da Wikipédia, teremos como objetivo gerar uma documentação automatizada que exibe um mindmap com o total de links da primeira página do site em português e em inglês.
Para essa tarefa vamos utilizar o python como linguagem de programação e alguns utilitários da linguagem como bs4() e requests.
Abaixo o código-fonte python e o plantUML script de saída
# import the necessary libraries
import itertools
from itertools import count
from bs4 import BeautifulSoup
import requests
def mindmap_of_page_links(url, name_of_branch):
# get the HTML of the Wikipedia home page
page = requests.get(url)
# parse the HTML using BeautifulSoup
soup = BeautifulSoup(page.content, 'html.parser')
# find all user interactions and network requests
interactions = soup.find_all("a", href=True)
# print the user interactions and network requests
print('* ' + name_of_branch + ' Wikipedia Page')
print('** links Found:', len(interactions))
for interaction in itertools.islice(interactions, 0, 5):
if interaction.text and interaction.text.strip():
print("*** Link Name: " + interaction.text.rstrip().lstrip() + " -> [[" + interaction['href'] + " ]]".rstrip())
print("@startmindmap")
mindmap_of_page_links("https://en.wikipedia.org/", 'EN')
mindmap_of_page_links("https://pt.wikipedia.org/", 'PT')
print("@endmindmap")@startmindmap
* EN Wikipedia Page
** links Found: 316
*** Link Name: Jump to navigation -> [[#mw-head ]]
*** Link Name: Jump to search -> [[#searchInput ]]
*** Link Name: Wikipedia -> [[/wiki/Wikipedia ]]
*** Link Name: free -> [[/wiki/Free_content ]]
*** Link Name: encyclopedia -> [[/wiki/Encyclopedia ]]
* PT Wikipedia Page
** links Found: 600
*** Link Name: Saltar para o conteúdo -> [[#bodyContent ]]
*** Link Name: Busca -> [[/wiki/Especial:Pesquisar ]]
*** Link Name: Criar uma conta -> [[/w/index.php?title=Especial:Criar_conta&returnto=Wikip%C3%A9dia%3AP%C3%A1gina+principal ]]
*** Link Name: Criar uma conta -> [[/w/index.php?title=Especial:Criar_conta&returnto=Wikip%C3%A9dia%3AP%C3%A1gina+principal ]]
@endmindmapVeja que desse modo automatizamos um documento gráfico que facilita a tomada de decisão em relação ao volume de links presentes na página.
No gráfico apresentado é possível visualizar facilmente que a página do Wikipedia em português tem um volume de links maior do que a página em inglês.
Através da automação realizada em python esse relatório poderia ser gerado facilmente e sem um esforço de documentação adicional.
Podemos ainda explorar outras possibilidades usando essa técnica de automação com documentação usando o PlantUML.
Deixo para vocês alguns referências sobre o tema:
Por hoje é isso, até a próxima jornada.
