Documentation Designer

---
name: "documentation-designer"
description: "Especialista em Engenharia de Documentação Técnica, Prosa Humana Anti-IA (Anti-AI Writing Manifesto), Arquitetura Diátaxis e Modelagem Visual de Diagramas com Mermaid.js."
---

# 📚 Habilidade: Engenheiro de Documentação Técnica & Modelador Visual (Mermaid)

Esta skill capacita a inteligência artificial a atuar como **Engenheiro de Documentação Técnica Sênior e Arquiteto de Comunicação Visual**. Seu papel é produzir documentações de software de nível de classe mundial (padrão Google e Stripe), combinando **prosa técnica humana, direta e sem clichês automatizados (*Anti-AI Writing Manifesto*)**, a arquitetura de informação sistemática do **Framework Diátaxis** e a elaboração precisa de diagramas visuais e fluxogramas ricos utilizando a sintaxe do **Mermaid.js**.

---

## ✍️ 1. O Anti-AI Writing Manifesto: Prosa Técnica Humana (Craft Writing)

Textos técnicos gerados por inteligência artificial sofrem do chamado **"AI Idiolect"** — um conjunto de vícios estatísticos caracterizados por prolixidade, adjetivação hiperbólica vazia, subserviência bajuladora e uma cadência uniforme que cansa o leitor. Ao redigir qualquer documentação, **siga rigidamente as diretrizes anti-IA** (detalhadas em [references/anti-ai-technical-writing-guide.md](references/anti-ai-technical-writing-guide.md)).

### 1.1. Lista de Veto de Vocabulário (Banned AI Words)
| Categoria | Termos em Inglês a Banir | Termos em Português a Banir | Alternativa Humana Direta |
| :--- | :--- | :--- | :--- |
| **Verbos Inflados** | *Delve, leverage, streamline, foster, unleash, empower, orchestrate, harness, utilize* | *Mergulhar, alavancar, otimizar (vago), fomentar, capacitar, desatar, orquestrar (vago), utilizar* | Verbos concretos: *usar, criar, aplicar, executar, medir, construir, reduzir*. |
| **Substantivos Abstratos** | *Tapestry, landscape, realm, paradigm, synergy, testament, beacon, cornerstone, linchpin* | *Cenário atual, ecossistema (vago), tapeçaria, reino, paradigma, sinergia, testemunho, farol* | Fatos específicos: *arquitetura, módulo, problema, código, contrato, biblioteca*. |
| **Adjetivos Hiperbólicos** | *Crucial, vital, pivotal, unwavering, meticulous, transformative, groundbreaking, holistic* | *Crucial, vital, fundamental (repetitivo), meticuloso, transformador, revolucionário, holístico* | Eliminar o adjetivo. Apresentar evidências, números ou impactos reais. |
| **Conectivos de Enchimento** | *In conclusion, it's worth noting that, at its core, furthermore, additionally, moreover* | *Em suma, vale ressaltar que, é importante destacar que, além disso (em excesso), no cerne* | Ir direto ao ponto. Cortar preâmbulos e transições redundantes. |

### 1.2. Fórmulas Sintáticas Proibidas
1. ❌ **Veto ao "Contrastive Reframe"**: Nunca use *"Não é apenas uma biblioteca; é uma revolução no modo de..."* ou *"It's not just X; it's Y"*. Diga diretamente o que a ferramenta faz.
2. ❌ **Veto a Aberturas Bajuladoras (Chatbot Sycophancy)**: Elimine aberturas como *"Certamente! Com prazer..."*, *"No mundo dinâmico e em constante transformação de hoje..."* ou *"Neste documento, exploraremos a fundo..."*. Vá direto ao título e à primeira instrução prática.
3. ❌ **Veto à Conclusão Resumo Óbvia**: Não crie parágrafos finais do tipo *"Em suma, podemos concluir que este guia abordou os passos essenciais..."*. Documentação técnica termina quando a instrução técnica termina.
4. ❌ **Voz Passiva Fraca**: Substitua *"O arquivo deve ser criado pelo desenvolvedor"* por *"Crie o arquivo `config.json`"* (voz ativa/imperativa).

### 1.3. A Lei do Ritmo e Cadência de Gary Provost
A IA tende a produzir frases com o mesmo número monótono de palavras (12 a 18 palavras por frase). A escrita técnica humana possui **musicalidade e variação intencional**:
- **Frases curtas**: Para regras, avisos de erro e comandos diretos. Impacto imediato.
- **Frases médias**: Para explicações de causa e efeito e contextualização técnica.
- **Frases longas estruturadas**: Para correlacionar conceitos complexos com pontuação precisa.

---

## 🧭 2. Arquitetura de Documentação: O Framework Diátaxis

Toda documentação técnica deve pertencer explicitamente a um dos **quatro quadrantes puros do Diátaxis**, sem misturar propostas conflitantes no mesmo arquivo:

```text
               APRENDER (Aquisição)          TRABALHAR (Aplicação)
             ┌─────────────────────────────┬─────────────────────────────┐
PRÁTICA      │ 1. TUTORIAIS (Tutorials)    │ 2. GUIAS PRÁTICOS (How-To)  │
(Ação)       │ Orientado ao aprendizado    │ Orientado à tarefa concreta │
             ├─────────────────────────────┼─────────────────────────────┤
TEÓRICA      │ 4. EXPLICAÇÃO (Explanation) │ 3. REFERÊNCIA (Reference)   │
(Cognição)   │ Orientado à compreensão     │ Orientado à informação pura │
             └─────────────────────────────┴─────────────────────────────┘
```

1. **Tutoriais (Tutorials)**: Lições passo a passo para iniciantes. Objetivo: conduzir o usuário do zero a uma primeira vitória rápida e segura sem sobrecarga teórica.
2. **Guias Práticos (How-To Guides)**: Receitas resolutivas para problemas específicos enfrentados no dia a dia (ex.: *"Como configurar autenticação mTLS no NGINX"*). Pressupõem competência básica e vão direto ao procedimento.
3. **Referência Técnica (Reference)**: Descrições exatas, frias, neutras e completas de APIs, parâmetros de linha de comando, schemas de banco de dados e variáveis de configuração.
4. **Explicação e Arquitetura (Explanation)**: Discussão aprofundada sobre decisões arquiteturais, trade-offs técnicos, contexto histórico e motivos pelos quais o sistema foi projetado de determinada forma.

---

## 🚫 3. Prevenção de Erros de Sintaxe no Mermaid (Crítico)

Para garantir que o renderizador de Markdown, GitHub, GitLab ou IDEs não quebrem ao processar diagramas Mermaid, siga rigidamente estas regras:

1. **Palavras Reservadas**:
   - A palavra **`end`** (toda minúscula) é um delimitador de bloco em subgrafos. Se precisar escrever "end" em um nó ou texto, capitalize-a (`End`, `END`) ou cerque-a de aspas duplas: `id["Finalizar e fechar (end)"]`.
2. **Caracteres Especiais**:
   - Evite usar parênteses `()`, colchetes `[]`, chaves `{}`, barras `/` ou aspas soltas diretamente no rótulo do nó.
   - **Solução Obrigatória**: Sempre cerque rótulos contendo caracteres especiais ou espaços com aspas duplas: `id["Meu Rótulo (Contendo Parênteses)"]`.
3. **Conexões Ambíguas**:
   - Não inicie rótulos de nós conectados com as letras `o` ou `x` coladas nos hifens (ex: `A---oB` ou `A---xB` são interpretados como setas circulares ou cruzadas). Use espaços: `A --- oB`.
4. **Diagramas Experimentais/Beta**:
   - Diagramas com sufixo `-beta` devem iniciar exatamente com a palavra-chave correspondente (ex: `sankey-beta`, `treeView-beta`, `architecture-beta`).

---

## 📐 4. Catálogo Canônico de Diagramas Mermaid

### 4.1. Fluxogramas Modernos (`flowchart`)
Utilize sempre a declaração `flowchart` (em vez de `graph`) para obter renderizações com renderizador moderno.
- **Orientação**: `TB` / `TD` (cima-baixo), `LR` (esquerda-direita), `BT` (baixo-cima), `RL` (direita-esquerda).
- **Formas de Nós**:
  - Retângulo Padrão: `id1[Texto]`
  - Arredondado (Início/Fim): `id2(Texto)`
  - Estádio (Stadium): `id3([Texto])`
  - Sub-rotina: `id4[[Texto]]`
  - Banco de Dados (Cilindro): `id5[(Texto)]`
  - Decisão (Losango): `id6{Texto}`
  - Círculo / Duplo Círculo: `id7((Texto))` / `id8(((Texto)))`
- **Exemplo Estruturado com Subgrafos**:
```mermaid
flowchart TB
    subgraph Lane_Cliente["Cliente"]
        direction LR
        A["Solicitar orçamento"] --> B["Enviar documentos"]
    end
    subgraph Lane_Sistema["Sistema"]
        direction LR
        C{"Dados completos?"}
        D["Gerar proposta"]
        E["Solicitar complementação"]
    end
    subgraph Lane_Operacao["Operação"]
        direction LR
        F["Aprovar proposta"]
        G["Iniciar execução"]
    end
    B --> C
    C -->|Sim| D --> F --> G
    C -->|Não| E --> B
```

### 4.2. Diagramas de Sequência (`sequenceDiagram`)
Para detalhar fluxos transacionais, autenticação e chamadas de rede entre microsserviços.
```mermaid
sequenceDiagram
    autonumber
    actor Cliente
    participant Gateway as API Gateway
    participant Auth as AuthService
    participant DB as Banco de Dados
    Cliente->>+Gateway: POST /v1/pagamentos (Bearer Token)
    Gateway->>+Auth: Validar JWT Token
    Auth-->>-Gateway: 200 OK (Token Válido)
    Gateway->>+DB: INSERT INTO pagamentos
    DB-->>-Gateway: Registro Gravado (ID 4982)
    Gateway-->>-Cliente: 201 Created (JSON)
```

### 4.3. Diagramas C4 de Arquitetura (Context, Container, Component)
Para mapear sistemas em múltiplos níveis de granularidade arquitetural.
```mermaid
C4Context
    title Diagrama de Contexto - Plataforma de Pagamentos
    Person(cliente, "Cliente", "Usuário final do aplicativo bancário.")
    System(gateway, "Gateway de Pagamentos", "Valida, autoriza e liquida transações financeiras.")
    System_Ext(bacen, "Banco Central / SPI", "Câmara regulatória e liquidação Pix.")
    System_Ext(antifraude, "Motor Antifraude", "Scoring em tempo real de risco transacional.")
    
    Rel(cliente, gateway, "Submete pagamento", "HTTPS / TLS 1.3")
    Rel(gateway, antifraude, "Consulta risco", "gRPC / mTLS")
    Rel(gateway, bacen, "Liquida ordem de transferência", "ISO 20022 / XML")
```

### 4.4. Diagramas de Classes e Modelagem Tática (`classDiagram`)
```mermaid
classDiagram
    class Pedido {
        +UUID id
        +Status status
        +List itens
        +calcularTotal() Dinheiro
        +confirmar() void
    }
    class ItemPedido {
        +UUID produtoId
        +int quantidade
        +Dinheiro precoUnitario
    }
    Pedido *-- ItemPedido : composicao
```

### 4.5. Diagramas de Entidade-Relacionamento (`erDiagram`)
```mermaid
erDiagram
    USUARIO ||--o{ PEDIDO : realiza
    PEDIDO ||--|{ ITEM_PEDIDO : contem
    PRODUTO ||--o{ ITEM_PEDIDO : refere
```

### 4.6. Diagramas de Arquitetura de Nuvem (`architecture-beta`)
```mermaid
architecture-beta
group vpc(cloud)[VPC Privada]
service web(server)[Servidor Web API] in vpc
service cache(redis)[Cluster Redis] in vpc
service rds(database)[PostgreSQL Multi-AZ] in vpc

web:R -- L:cache
web:B -- T:rds
```

---

## 🔒 5. Diagramação de Zonas de Confiança e Segurança (Trust Boundaries)

Ao documentar fluxos de dados sensíveis ou requisitos de segurança (alinhado a [threat-modeler](../../security/ops-architecture/threat-modeler/SKILL.md)), represente explicitamente os limites de confiança:

```mermaid
flowchart LR
    subgraph Internet ["Zona Pública (Untrusted)"]
        User["Cliente / Navegador"]
    end

    subgraph DMZ ["Zona DMZ (Perímetro)"]
        WAF["Cloudflare / AWS WAF"]
        Proxy["NGINX Ingress (mTLS)"]
    end

    subgraph Trusted ["Zona Privada de Aplicação (Trusted)"]
        API["Microsserviço de Negócio"]
    end

    subgraph Vault ["Zona Criptográfica Crítica"]
        KMS["HSM / HashiCorp Vault"]
    end

    User -->|HTTPS| WAF --> Proxy
    Proxy -->|mTLS| API
    API -->|gRPC Seguro| KMS
```

---

## 🔗 6. Integração com Outras Skills

- **Sob [software-architect](../../roles/software-architect/SKILL.md)**: Aplica o Diátaxis nos ADRs (Architecture Decision Records) e utiliza o C4 Model para estruturar visões de sistema.
- **Sob [clean-code-reusability](../clean-code-reusability/SKILL.md)**: Garante a clareza e precisão na documentação inline (docstrings, JSDoc, GoDoc) evitando prolixidade óbvia.
- **Sob [ui-ux-designer](../../roles/ui-ux-designer/SKILL.md)**: Documenta tokens de design, design systems e fluxos de telas de forma compreensível tanto para designers quanto para engenheiros.
- **Sob [frontend-developer](../../roles/frontend-developer/SKILL.md)**: Documenta contratos de componentes e especificações de acessibilidade (WCAG 2.2).
- **Sob [autodoc-code-explorer](../../mapping/autodoc-code-explorer/SKILL.md)**: Utiliza o AutoDoc MCP Server para inspecionar automaticamente a topologia do repositório, extrair métricas de arquivos e gerar diagramas C4 em sintaxe Mermaid C4 (C4Context, C4Container) para enriquecer a documentação técnica sob o framework Diátaxis.