Quais são algumas dicas para visualizar a documentação técnica?

Para ser honesto, a maior dor de cabeça na documentação técnica é como tornar esses conceitos abstractos compreensíveis. Na semana passada, deparei-me com uma situação típica - para explicar a arquitetura de microsserviços aos novos estagiários, baseei-me em descrições de texto para falar durante meio dia, olhando para os seus olhos confusos, e de repente apercebi-me de que: os documentos técnicos têm de ser visuais, mas visual não é o mesmo que simplesmente desenhar umas caixas com umas linhas tão simples.

A escolha do tipo correto de gráfico é importante

Diferentes tipos de documentos requerem diferentes visualizações. Os documentos de arquitetura utilizam diagramas de arquitetura, as descrições de processos utilizam fluxogramas e as relações de dados utilizam diagramas ER, o que parece ser senso comum, mas muitas pessoas confundem-se. Já vi pessoas utilizarem mapas mentais para mostrar a arquitetura do sistema e acabarem por confundir as relações hierárquicas claras. Por exemplo, se quiser ilustrar o processo de início de sessão do utilizador, um diagrama de tempo seria mais adequado do que um diagrama de arquitetura, porque mostraria claramente a ordem de interação entre os componentes.

Manter a coerência visual é fundamental

Isto é muito importante! Já vi muitos documentos técnicos com gráficos de várias cores, tamanhos de letra diferentes e até o estilo das setas não é uniforme. Esta confusão visual irá afetar seriamente a experiência de leitura. Recomenda-se que defina um conjunto de especificações de design antes de começar: qual é a cor principal, que cores secundárias escolher, como definir o tamanho da letra, como uniformizar a espessura e o estilo das linhas de ligação. Tal como o Smart Excalidraw, ajuda-o automaticamente a manter a consistência visual, poupando-lhe muito esforço de ajuste.

A hierarquia deve ser claramente visível

O maior receio da documentação técnica é complicar problemas simples. Uma boa visualização deve permitir que o leitor veja num relance onde está o foco e qual é a hierarquia. Por exemplo, num diagrama de arquitetura, os componentes principais devem ter cores mais chamativas ou tamanhos maiores, e os componentes secundários podem ser adequadamente enfraquecidos. Através de uma disposição e agrupamento razoáveis, a hierarquia da informação é apresentada de forma natural. Lembro-me de uma vez que optimizei um diagrama de arquitetura de um sistema, ajustando apenas a posição e o tamanho dos componentes, de modo que a relação hierárquica de toda a arquitetura ficou duas vezes mais clara.

As notas e as etiquetas devem ser corretas

A chave não é ter o maior número possível de descrições de texto na tabela, mas ter a rotulagem necessária nos sítios necessários. Já vi alguns gráficos em que cada componente está cheio de instruções, o resultado é que as pessoas não conseguem encontrar o foco. De facto, basta uma descrição concisa para que os nós-chave sejam facilmente ambíguos. Uma ferramenta como o Smart Excalidraw é boa, pois gera diagramas com notas bem colocadas que não parecem estar cheias.

No fim de contas, o mais importante na visualização de documentos técnicos não é a beleza do desenho do diagrama, mas a eficácia com que a informação é transmitida. Por vezes, um simples esboço, desde que consiga transmitir o significado com exatidão, é mais valioso do que aqueles esboços extravagantes, mas pouco claros, que se centram na complexidade do diagrama. Afinal de contas, o objetivo da nossa documentação técnica é ser compreendida e não ser exibida.