documentation-designer

# 📚 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.