@maestro-ai/mcp-server 1.1.0 → 2.0.0

package/dist/content/skills/specialist-documentacao-tecnica/resources/reference/documentation-guide.md

@@ -0,0 +1,798 @@
+# 📚 Guia Completo de Documentação Técnica
+
+## 🎯 Visão Geral
+
+Este guia aborda as melhores práticas para criar documentação técnica eficaz, desde READMEs até APIs docs, passando por arquitetura e guias de usuário.
+
+### Princípios Fundamentais
+1. **Documentação é Código** - Trate com o mesmo rigor
+2. **Usuário em Primeiro Lugar** - Escreva para quem vai usar
+3. **Manutenção Contínua** - Mantenha sempre atualizada
+4. **Exemplos Funcionais** - Teste tudo que documenta
+
+---
+
+## 🏗️ Tipos de Documentação
+
+### 1. README.md (O Cartão de Visitas)
+
+#### Propósito
+Primeiro contato com o projeto. Deve responder imediatamente:
+- O que este projeto faz?
+- Por que existe?
+- Como começar a usar?
+
+#### Estrutura Obrigatória
+```markdown
+# 🚀 [Nome do Projeto]
+
+> [Descrição impactante em uma linha]
+
+[Badges importantes]
+
+## 🎯 Sobre
+[2-3 parágrafos explicando o projeto]
+
+## ✨ Features
+- **Feature principal:** Benefício claro
+- **Feature secundária:** Outro benefício
+
+## 🛠️ Stack Tecnológica
+- **Frontend:** Tecnologias usadas
+- **Backend:** Tecnologias usadas
+
+## 🚀 Getting Started
+### Pré-requisitos
+- Node.js X.X.X
+- Docker (opcional)
+
+### Instalação
+```bash
+git clone [URL]
+cd [projeto]
+npm install
+cp .env.example .env
+npm run dev
+```
+
+## 📁 Estrutura do Projeto
+[Diretório principal com descrições]
+
+## 🔧 Scripts Disponíveis
+[Lista de scripts npm/yarn]
+
+## 📞 Contribuição
+[Breve guia de como contribuir]
+
+## 📄 Licença
+[Tipo de licença]
+```
+
+#### Melhores Práticas
+- **Título claro** e descritivo
+- **Badges informativos** (build, coverage, versão)
+- **Getting Started funcional** (copy-paste funciona)
+- **Exemplos práticos** e testados
+- **Links úteis** para documentação adicional
+
+---
+
+### 2. API Documentation
+
+#### Propósito
+Documentar endpoints, autenticação, exemplos e casos de uso para desenvolvedores.
+
+#### Estrutura Recomendada
+```markdown
+# 📡 [Nome da API] Documentation
+
+## 🔐 Autenticação
+[Método de autenticação com exemplos]
+
+## 📊 Resumo da API
+[Tabela com endpoints principais]
+
+## 📋 Endpoints Detalhados
+### GET /endpoint
+[Descrição completa com parameters, responses, errors]
+
+## 📊 Data Models
+[Estruturas de dados documentadas]
+
+## ⚠️ Error Handling
+[Códigos de erro e exemplos]
+
+## 🧪 Exemplos e SDKs
+[Código de exemplo em múltiplas linguagens]
+```
+
+#### Padrões de Documentação de Endpoint
+```markdown
+### [MÉTODO] [ENDPOINT]
+[Descrição clara do que faz]
+
+#### Request
+```bash
+curl -X [MÉTODO] \
+     -H "Content-Type: application/json" \
+     -H "Authorization: Bearer <TOKEN>" \
+     -d '[REQUEST_BODY]' \
+     [URL]
+```
+
+#### Parameters
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|-----------|------|-------------|-----------|
+| param1 | string | Sim | Descrição do parâmetro |
+
+#### Response 200
+```json
+{
+  "data": [RESPONSE_STRUCTURE]
+}
+```
+
+#### Error Responses
+- **400 Bad Request:** Parâmetros inválidos
+- **401 Unauthorized:** Não autorizado
+- **404 Not Found:** Recurso não encontrado
+```
+
+---
+
+### 3. Architecture Decision Records (ADRs)
+
+#### Propósito
+Documentar decisões arquiteturais importantes com contexto, alternativas e consequências.
+
+#### Template Padrão
+```markdown
+# ADR-XXX: [Título Curto e Descritivo]
+
+## Status
+[Accepted | Rejected | Proposed | Deprecated]
+
+## Contexto
+[Descrição do problema ou situação que levou à decisão]
+
+## Decisão
+[Decisão tomada de forma clara e concisa]
+
+## Razões
+[Lista de razões que justificam a decisão]
+
+## Consequências
+[Impactos positivos e negativos da decisão]
+
+## Alternativas Consideradas
+[Outras opções avaliadas e por que não foram escolhidas]
+
+## Data
+[Data da decisão]
+
+## Implementação
+[Como a decisão foi implementada]
+```
+
+#### Exemplo Real
+```markdown
+# ADR-001: Escolha de React para Frontend
+
+## Status
+Accepted
+
+## Contexto
+Precisamos escolher framework frontend para novo sistema de gestão. Equipe tem experiência mista, prazo apertado, necessidade de performance.
+
+## Decisão
+Usar React 18 com TypeScript e Next.js 13.
+
+## Razões
+- **Performance:** React 18 com Concurrent Features
+- **Ecosystem:** Bibliotecas maduras e comunidade ativa
+- **Team Skills:** 60% da equipe já conhece React
+- **Type Safety:** TypeScript para redução de bugs
+- **SEO:** Next.js para server-side rendering
+
+## Consequências
+✅ Desenvolvimento rápido com curva de aprendizado baixa
+✅ Performance otimizada com SSR/SSG
+✅ SEO amigável por padrão
+❌ Bundle size maior que alternativas leves
+❌ Complexidade adicional com Next.js
+
+## Alternativas Consideradas
+- **Vue.js:** Mais simples mas ecossistema menor
+- **Svelte:** Performance melhor mas equipe inexperiente
+- **Angular:** Muito robusto mas curva de aprendizado alta
+
+## Data
+2024-01-15
+
+## Implementação
+- Criar projeto Next.js com TypeScript
+- Configurar ESLint + Prettier
+- Implementar estrutura de componentes
+- Configurar testing com Jest + Testing Library
+```
+
+---
+
+### 4. Contributing Guide
+
+#### Propósito
+Guiar novos contribuidores sobre como participar do projeto.
+
+#### Estrutura Essencial
+```markdown
+# 🤝 Contribuindo para [Projeto]
+
+Obrigado por interesse em contribuir! Este guia ajuda você a começar.
+
+## 🚀 Como Começar
+
+### 1. Fork e Clone
+```bash
+git clone https://github.com/SEU_USERNAME/projeto.git
+cd projeto
+```
+
+### 2. Setup do Ambiente
+```bash
+npm install
+cp .env.example .env
+npm run dev
+```
+
+### 3. Crie uma Branch
+```bash
+git checkout -b feature/nova-feature
+```
+
+## 📝 Convenções de Commit
+
+Usamos [Conventional Commits](https://conventionalcommits.org/):
+
+```
+feat: nova funcionalidade
+fix: correção de bug
+docs: documentação
+style: formatação
+refactor: refatoração
+test: testes
+chore: build process
+```
+
+## 🧪 Testes
+```bash
+npm test                    # Todos os testes
+npm run test:coverage      # Com cobertura
+npm run test:watch         # Modo watch
+```
+
+## 📋 Processo de Pull Request
+
+1. **Atualize sua branch**
+   ```bash
+   git pull upstream main
+   ```
+
+2. **Faça seus commits**
+   ```bash
+   git add .
+   git commit -m "feat: add user authentication"
+   ```
+
+3. **Push e abra PR**
+   ```bash
+   git push origin feature/nova-feature
+   ```
+
+4. **Preencha o template de PR**
+
+## 🎯 O que Contribuir
+
+### ✅ Bem-vindo
+- Bug fixes
+- Novas features
+- Melhorias na documentação
+- Testes adicionais
+- Performance improvements
+
+### ❌ Evite
+- Breaking changes sem discussão
+- Dependências desnecessárias
+- Código sem testes
+- Documentação desatualizada
+
+## 📞 Dúvidas?
+
+- **Discord:** #contribuidores
+- **Issues:** Use templates adequados
+- **Email:** dev@projeto.com
+```
+
+---
+
+## 🎨 Escrita Técnica Eficaz
+
+### Princípios de Clareza
+
+#### 1. Conheça seu Público
+```markdown
+❌ Ruim: "O sistema utiliza um ORM para mapeamento objeto-relacional..."
+✅ Bom: "Usamos Prisma para conectar nosso código JavaScript com o banco PostgreSQL..."
+```
+
+#### 2. Seja Específico
+```markdown
+❌ Ruim: "Configure as variáveis de ambiente"
+✅ Bom: "Copie .env.example para .env e configure DATABASE_URL com sua string de conexão PostgreSQL"
+```
+
+#### 3. Use Exemplos Funcionais
+```markdown
+❌ Ruim: "Para criar um usuário, envie uma requisição POST"
+✅ Bom: "Para criar um usuário, execute:"
+```bash
+curl -X POST \
+     -H "Content-Type: application/json" \
+     -d '{"name":"João","email":"joao@exemplo.com"}' \
+     http://localhost:3000/api/users
+```
+
+### Estrutura de Conteúdo
+
+#### Hierarquia de Informação
+1. **O quê** - O que esta coisa faz?
+2. **Por quê** - Por que existe? Qual problema resolve?
+3. **Como** - Como usar? Exemplos práticos
+4. **Detalhes** - Informações técnicas avançadas
+
+#### Padrão de Exemplos
+```markdown
+## 🎯 Objetivo
+[Breve descrição do que o exemplo demonstra]
+
+## 📋 Pré-requisitos
+[O que precisa estar configurado]
+
+## 🔧 Implementação
+[Código ou comandos]
+
+## ✅ Resultado Esperado
+[O que deve acontecer]
+
+## 🔍 Troubleshooting
+[Problemas comuns e soluções]
+```
+
+---
+
+## 🛠️ Ferramentas e Automação
+
+### Geração Automática de Docs
+
+#### OpenAPI/Swagger
+```yaml
+# swagger.yaml
+openapi: 3.0.0
+info:
+  title: Minha API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: Lista usuários
+      responses:
+        '200':
+          description: Lista de usuários
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+```
+
+#### TypeDoc para TypeScript
+```typescript
+/**
+ * Representa um usuário do sistema
+ * @example
+ * ```typescript
+ * const user: User = {
+ *   id: 1,
+ *   name: "João Silva",
+ *   email: "joao@exemplo.com"
+ * };
+ * ```
+ */
+export interface User {
+  /** ID único do usuário */
+  id: number;
+  /** Nome completo do usuário */
+  name: string;
+  /** Email válido do usuário */
+  email: string;
+  /** Data de criação */
+  createdAt: Date;
+}
+```
+
+### Ferramentas de Validação
+
+#### Markdown Lint
+```json
+// .markdownlint.json
+{
+  "default": true,
+  "MD013": false, // Line length
+  "MD033": false, // HTML elements
+  "MD041": false  // First line heading
+}
+```
+
+#### Link Checking
+```bash
+# Verifica links quebrados
+npm install -g markdown-link-check
+markdown-link-check README.md
+
+# Verifica todos os arquivos markdown
+find . -name "*.md" -exec markdown-link-check {} \;
+```
+
+---
+
+## 📊 Métricas e Qualidade
+
+### Indicadores de Qualidade
+
+#### Métricas Objetivas
+- **Coverage de Documentação:** % de APIs documentadas
+- **Freshness:** Dias desde última atualização
+- **Accuracy:** % de exemplos funcionais
+- **Completeness:** Score baseado em checklist
+
+#### Métricas Subjetivas
+- **Clareza:** Pesquisa com usuários (1-5)
+- **Utilidade:** Feedback de desenvolvedores
+- **Facilidade:** Tempo para encontrar informação
+
+### Checklist de Qualidade
+
+#### Nível Básico (Obrigatório)
+- [ ] README com getting started funcional
+- [ ] API docs sincronizadas com código
+- [ ] Exemplos testados e funcionando
+- [ ] Links internos e externos funcionando
+- [ ] Formatação consistente
+
+#### Nível Intermediário (Recomendado)
+- [ ] Architecture Decision Records
+- [ ] Contributing guide
+- [ ] Troubleshooting section
+- [ ] Performance considerations
+- [ ] Security guidelines
+
+#### Nível Avançado (Excelência)
+- [ ] Interactive tutorials
+- [ ] Video walkthroughs
+- [ ] Code examples em múltiplas linguagens
+- [ ] Performance benchmarks
+- [ ] Migration guides
+
+---
+
+## 🔄 Manutenção Contínua
+
+### Processo de Atualização
+
+#### 1. Integrado ao Desenvolvimento
+```yaml
+# .github/workflows/docs.yml
+name: Documentation Check
+on: [push, pull_request]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Check markdown
+        run: |
+          npm run lint:markdown
+          npm run check:links
+      - name: Validate examples
+        run: npm run test:examples
+```
+
+#### 2. Revisão Periódica
+- **Semanal:** Verificação de links quebrados
+- **Mensal:** Revisão de conteúdo e exemplos
+- **Trimestral:** Auditoria completa de qualidade
+- **Semestral:** Reestruturação baseada em feedback
+
+#### 3. Feedback Loop
+```markdown
+## 📝 Feedback da Documentação
+
+Esta documentação foi útil?
+- [ ] Sim
+- [ ] Parcialmente
+- [ ] Não
+
+O que poderia ser melhorado?
+__________________________________________
+
+[Enviar Feedback]
+```
+
+### Versionamento da Documentação
+
+#### Estratégia de Versionamento
+```markdown
+# 📋 Versionamento
+
+## v2.1.0 (Atual)
+- Atualizado para API v2.1
+- Novos exemplos de autenticação
+- Corrigidos links quebrados
+
+## v2.0.0
+- Documentação reestruturada
+- Novo formato de API docs
+- Migração de v1 para v2
+
+## v1.x.x (Arquivo)
+- Mantido para referência
+- Não atualizado ativamente
+```
+
+---
+
+## 🎯 Casos de Uso Específicos
+
+### Documentação para APIs REST
+
+#### Estrutura Completa
+```markdown
+# 📡 [API Name] v[X.X.X]
+
+## 🔐 Autenticação
+### Bearer Token
+```bash
+curl -H "Authorization: Bearer <TOKEN>" https://api.example.com/v1
+```
+
+### API Key
+```bash
+curl -H "X-API-Key: <KEY>" https://api.example.com/v1
+```
+
+## 📊 Rate Limiting
+- **Limit:** 1000 requests/hour
+- **Headers:** X-RateLimit-Limit, X-RateLimit-Remaining
+
+## 📋 Endpoints
+
+### Users
+#### GET /users
+Lista usuários com paginação e filtros.
+
+**Query Parameters:**
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| page | number | 1 | Número da página |
+| limit | number | 20 | Items por página |
+| search | string | - | Busca por nome/email |
+
+**Response 200:**
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+**Error Responses:**
+- 400: Bad Request
+- 401: Unauthorized
+- 429: Rate Limit Exceeded
+```
+
+### Documentação para Bibliotecas/SDKs
+
+#### Estrutura Recomendada
+```markdown
+# 📦 [Library Name] SDK
+
+## 🚀 Instalação
+```bash
+npm install [library-name]
+```
+
+## 🔧 Configuração
+```javascript
+import { LibraryClient } from '[library-name]';
+
+const client = new LibraryClient({
+  apiKey: 'your-api-key',
+  baseURL: 'https://api.example.com'
+});
+```
+
+## 📋 Exemplos de Uso
+
+### Básico
+```javascript
+// Criar usuário
+const user = await client.users.create({
+  name: 'João Silva',
+  email: 'joao@exemplo.com'
+});
+
+console.log(user.id); // 123
+```
+
+### Avançado
+```javascript
+// Com tratamento de erros
+try {
+  const users = await client.users.list({
+    page: 1,
+    limit: 10,
+    filters: { active: true }
+  });
+} catch (error) {
+  if (error.status === 401) {
+    console.log('API key inválida');
+  }
+}
+```
+
+## 📚 Referência da API
+
+### Users
+#### create(data)
+Cria um novo usuário.
+
+**Parameters:**
+- `data` (Object): Dados do usuário
+  - `name` (string): Nome do usuário
+  - `email` (string): Email válido
+
+**Returns:** Promise<User>
+
+**Example:**
+```javascript
+const user = await client.users.create({
+  name: 'Maria',
+  email: 'maria@exemplo.com'
+});
+```
+```
+
+---
+
+## 🚀 Publicação e Distribuição
+
+### Plataformas de Hospedagem
+
+#### GitHub Pages
+```yaml
+# .github/workflows/deploy-docs.yml
+name: Deploy Documentation
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      - name: Install dependencies
+        run: npm install
+      - name: Build docs
+        run: npm run build:docs
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/dist
+```
+
+#### ReadTheDocs
+```yaml
+# .readthedocs.yml
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+sphinx:
+  configuration: docs/conf.py
+python:
+  install:
+    - requirements: docs/requirements.txt
+```
+
+### SEO e Descoberta
+
+#### Meta Tags para Docs
+```html
+<head>
+  <title>API Documentation - Project Name</title>
+  <meta name="description" content="Complete API documentation for Project Name">
+  <meta name="keywords" content="api, documentation, rest, json">
+  
+  <!-- Open Graph -->
+  <meta property="og:title" content="API Documentation">
+  <meta property="og:description" content="Complete API documentation">
+  <meta property="og:type" content="website">
+  
+  <!-- JSON-LD -->
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    "headline": "API Documentation",
+    "description": "Complete API documentation"
+  }
+  </script>
+</head>
+```
+
+---
+
+## 📞 Suporte e Comunidade
+
+### Canais de Comunicação
+- **Issues:** Para bugs e feature requests
+- **Discussions:** Para dúvidas e discussões
+- **Discord/Slack:** Para conversas em tempo real
+- **Email:** Para contato direto
+
+### Processo de Feedback
+1. **Coleta:** Formulários e analytics
+2. **Análise:** Identificação de padrões
+3. **Priorização:** Baseado em impacto
+4. **Implementação:** Atualizações iterativas
+5. **Comunicação:** Divulgação das melhorias
+
+---
+
+## 🎯 Conclusão
+
+Documentação técnica eficaz é um investimento contínuo que:
+- **Reduz suporte** e tempo de onboarding
+- **Aumenta adoção** e satisfação do usuário
+- **Melhora qualidade** do código através de clareza
+- **Acelera desenvolvimento** com exemplos práticos
+
+Lembre-se: **Documentação não é um afterthought, é parte do produto.**
+
+---
+
+**Última atualização:** [Data atual]  
+**Versão:** v2.1  
+**Próxima revisão:** [Data + 3 meses]