diff --git a/DOCUMENTATION_ANALYSIS.md b/DOCUMENTATION_ANALYSIS.md new file mode 100644 index 00000000000..87b433617b7 --- /dev/null +++ b/DOCUMENTATION_ANALYSIS.md @@ -0,0 +1,969 @@ +# Análise e Oportunidades de Melhoria da Documentação Ansible + +**Data da Análise:** 2025-11-22 +**Status:** Em Progresso +**Versão:** 1.0 + +--- + +## 📊 Sumário Executivo + +A documentação do Ansible contém **471 arquivos RST** distribuídos em **29 diretórios principais**. Apesar de bem estruturada em nível arquitetural, sofre de problemas relacionados a refatorações incompletas, fragmentação de conteúdo e inconsistências que impactam a experiência do usuário. + +### Principais Descobertas + +- ✅ **Pontos Fortes:** Estrutura modular clara, separação por tópicos, cobertura abrangente +- ⚠️ **Desafios Críticos:** 25+ arquivos stub com redirecionamentos, duas estruturas competindo (user_guide vs novos guias) +- 🎯 **Oportunidade Principal:** Consolidação da estrutura e eliminação de redundâncias + +--- + +## 🗂️ Estrutura Atual da Documentação + +### Diretórios Principais + +``` +docs/docsite/rst/ +├── 📘 getting_started/ # Guias de início para novos usuários +├── 📘 getting_started_ee/ # Execution Environments (EE) +├── 📦 installation_guide/ # Instalação do Ansible (MÍNIMO - 4 arquivos) +├── 📋 inventory_guide/ # Gestão de inventários +├── ⚡ command_guide/ # Ferramentas CLI (ansible, ansible-playbook) +├── 📖 playbook_guide/ # Playbooks (SEÇÃO MAIS COMPLETA) +├── 🔐 vault_guide/ # Ansible Vault (segurança) +├── 📦 collections_guide/ # Uso de collections +├── 🧩 module_plugin_guide/ # Referência de módulos/plugins +├── 💻 dev_guide/ # Desenvolvimento (EXTENSO - ~450KB) +├── 👥 community/ # Contribuição comunitária +├── 🖥️ os_guide/ # Guias por sistema operacional +├── 🌐 network/ # Network Automation (ISOLADO) +├── 📚 scenario_guides/ # Cenários práticos (DESCONTINUADO) +├── 🔄 porting_guides/ # Migração entre versões (29 guias!) +├── 📎 reference_appendices/ # Referências gerais +├── 💡 tips_tricks/ # Dicas e truques +├── 🔌 api/ # API do Ansible +├── 📦 collections/ # Índice de collections +├── 🌟 galaxy/ # Ansible Galaxy +├── 🔧 plugins/ # Documentação de plugins +├── 🗺️ roadmap/ # Roadmaps do projeto +└── 🌍 locales/ # Traduções (japonês) + +⚠️ DEPRECIADOS/PROBLEMAS: +├── ❌ user_guide/ # DEPRECIADO - apenas stubs/redirecionamentos +└── ⚠️ scenario_guides/ # DESCONTINUADO - migrando para collections +``` + +### Estatísticas + +| Métrica | Valor | +|---------|-------| +| **Total de arquivos RST** | 471 | +| **Total de linhas** | ~55.545 | +| **Diretórios principais** | 29 | +| **Arquivos de índice** | 21 | +| **Arquivos com 2000+ linhas** | 2 (playbooks_filters.rst, porting_guide_12.rst) | +| **Arquivos stub (<100 linhas)** | ~50 | +| **Redirecionamentos encontrados** | 25+ | +| **Seções depreciadas** | 2 (user_guide, scenario_guides) | + +--- + +## 🚨 Problemas Críticos Identificados + +### 1. FALTA DE CONTEÚDO DIRETO - Stubs e Redirecionamentos + +**Severidade:** 🔴 CRÍTICA +**Impacto:** Alto - Experiência do usuário degradada +**Esforço para correção:** Moderado (4-6 horas) + +#### Descrição do Problema + +Mais de **25 arquivos** no diretório `/user_guide/` são apenas redirecionamentos de 4-6 linhas: + +**Exemplos encontrados:** + +```rst +# user_guide/playbooks.rst (5 linhas) +This page has moved to :ref:`working_with_playbooks`. + +# user_guide/modules.rst (5 linhas) +This page has moved to :ref:`modules_plugins_index`. + +# user_guide/windows_faq.rst (5 linhas) +This page has moved to :ref:`working_with_windows`. +``` + +#### Arquivos Afetados + +- `playbooks.rst`, `playbooks_async.rst`, `playbooks_delegation.rst` +- `playbooks_environment.rst`, `playbooks_handlers.rst`, `playbooks_loops.rst` +- `modules.rst`, `windows_setup.rst`, `windows_usage.rst` +- E mais 15+ arquivos similares + +#### Impacto + +- Usuários redirecionados múltiplas vezes +- Links favoritos e bookmarks quebrados +- Confusão sobre estrutura da documentação +- Perda de SEO e PageRank + +#### Solução Recomendada + +1. **Curto prazo:** Adicionar nota explicativa em cada stub sobre a migração +2. **Médio prazo:** Implementar redirecionamentos no `conf.py` do Sphinx +3. **Longo prazo:** Remover completamente os stubs após período de transição + +--- + +### 2. DUAS ESTRUTURAS COMPETINDO + +**Severidade:** 🔴 CRÍTICA +**Impacto:** Alto - Confusão organizacional +**Esforço para correção:** Alto (6-8 horas) + +#### Descrição do Problema + +Existem duas estruturas de documentação paralelas: + +1. **Estrutura ANTIGA** (`user_guide/`) - Quase vazia, apenas stubs +2. **Estrutura NOVA** (`playbook_guide/`, `command_guide/`, `inventory_guide/`) - Completa e ativa + +#### Evidência de Depreciação + +O arquivo `/user_guide/index.rst` contém: + +```rst +.. note:: + Welcome to the Ansible User Guide! + This guide is now deprecated to improve navigation and organization. + You can find all the user guide content in the following sections: + * :ref:`inventory_guide_index` + * :ref:`command_guide_index` + * :ref:`playbook_guide_index` +``` + +#### Problemas Decorrentes + +- Backlinks externos quebrados +- Duplicação de esforços de manutenção +- Usuários não sabem qual estrutura seguir +- Inconsistência na experiência + +#### Solução Recomendada + +1. **Fase 1:** Documentar claramente a nova estrutura +2. **Fase 2:** Atualizar todos os links internos +3. **Fase 3:** Implementar HTTP 301 redirects +4. **Fase 4:** Remover diretório `user_guide/` completamente + +--- + +### 3. SCENARIO GUIDES DESCONTINUADA + +**Severidade:** 🟡 ALTA +**Impacto:** Médio - Conteúdo desatualizado +**Esforço para correção:** Médio (4-6 horas) + +#### Descrição do Problema + +O arquivo `/scenario_guides/guides.rst` admite abertamente: + +```rst +The guides in this section are migrating into collections. +Remaining guides may be out of date. + +We are migrating these guides into collections. +Please update your links for the following guides: +:ref:`ansible_collections.amazon.aws.docsite.aws_intro` +``` + +#### Guias Afetados + +- AWS/Amazon guides → `amazon.aws` collection +- Docker guides → Collections específicas +- Cloud providers (Azure, GCP, OpenStack, etc.) +- Kubernetes/OpenShift + +#### Impacto + +- Documentação desatualizada confunde usuários +- Links quebrados para guias migrados +- Usuários não sabem onde encontrar conteúdo atualizado + +#### Solução Recomendada + +1. Criar página de mapeamento: **Old Guide → New Collection** +2. Adicionar warnings claros em cada guia descontinuado +3. Estabelecer timeline de remoção (ex: após 2 major releases) +4. Arquivar guias antigos em seção separada + +--- + +### 4. ARQUIVOS MUITO GRANDES + +**Severidade:** 🟡 MÉDIA +**Impacto:** Médio - Dificuldade de manutenção +**Esforço para correção:** Alto (6-10 horas por arquivo) + +#### Arquivos Problemáticos + +| Arquivo | Linhas | Problema | +|---------|--------|----------| +| `playbooks_filters.rst` | 2.205 | Todos os filtros em um único arquivo | +| `porting_guide_12.rst` | 1.523 | Guia de migração muito extenso | +| `porting_guide_7.rst` | 1.290 | Guia de migração muito extenso | +| `developing_modules_documenting.rst` | 935 | Documentação massiva de módulos | +| `windows_winrm.rst` | 632 | Configuração WinRM muito detalhada | + +#### Impacto + +- Difícil de navegar e encontrar informação específica +- Longo tempo de carregamento +- Difícil de manter e atualizar +- Usuários sobrecarregados com informação + +#### Solução Recomendada + +**Para `playbooks_filters.rst`:** +``` +playbooks_filters.rst (índice geral) +├── playbooks_filters_basic.rst (filters básicos) +├── playbooks_filters_text.rst (manipulação de texto) +├── playbooks_filters_list.rst (listas e arrays) +├── playbooks_filters_math.rst (operações matemáticas) +└── playbooks_filters_network.rst (filtros de rede) +``` + +**Para porting guides:** +- Dividir por categoria: Breaking Changes, Deprecations, New Features +- Criar sub-páginas por área (Core, Collections, Plugins) + +--- + +### 5. DOCUMENTAÇÃO FRAGMENTADA - Windows + +**Severidade:** 🟡 ALTA +**Impacto:** Alto - Usuários Windows perdidos +**Esforço para correção:** Alto (8-12 horas) + +#### Distribuição Atual + +Documentação de Windows está espalhada em **3+ localizações**: + +1. **`/os_guide/intro_windows.rst`** - Introdução básica +2. **`/os_guide/windows_*.rst`** - 12 arquivos específicos (setup, WinRM, FAQ, etc.) +3. **`/user_guide/windows_*.rst`** - 6 stubs com redirecionamentos +4. **`/dev_guide/developing_modules_general_windows.rst`** - 741 linhas sobre desenvolvimento + +#### Impacto + +- Usuários não sabem onde começar +- Conteúdo duplicado ou contradictório +- Difícil manter sincronizado +- Experiência de aprendizado fragmentada + +#### Solução Recomendada + +**Consolidar em `/os_guide/windows/`:** + +``` +os_guide/windows/ +├── index.rst # Índice principal +├── getting_started.rst # Primeiros passos +├── setup.rst # Setup e instalação +├── winrm.rst # Configuração WinRM +├── authentication.rst # Autenticação +├── modules.rst # Módulos Windows +├── troubleshooting.rst # Solução de problemas +├── faq.rst # FAQ +├── best_practices.rst # Melhores práticas +└── development/ # Sub-diretório para devs + ├── index.rst + ├── developing_modules.rst + └── testing.rst +``` + +--- + +### 6. DOCUMENTAÇÃO DE COLLECTIONS FRAGMENTADA + +**Severidade:** 🟡 MÉDIA +**Impacto:** Médio - Confusão sobre collections +**Esforço para correção:** Alto (10-15 horas) + +#### Distribuição Atual + +Documentação de collections está em **múltiplos lugares**: + +1. **`/collections_guide/`** - 7 arquivos sobre uso de collections +2. **`/collections/`** - Apenas índice +3. **`/dev_guide/developing_collections_*`** - 16 arquivos sobre desenvolvimento +4. **`/community/`** - Informações sobre contribuição + +#### Problema + +Usuários não sabem: +- Onde aprender sobre collections +- Como usar collections +- Como desenvolver collections +- Diferença entre usar e criar + +#### Solução Recomendada + +**Reorganizar em estrutura clara:** + +``` +collections_guide/ +├── index.rst # Visão geral +├── using_collections/ # Para USUÁRIOS +│ ├── index.rst +│ ├── installing.rst +│ ├── using_modules.rst +│ └── requirements.rst +├── developing_collections/ # Para DESENVOLVEDORES +│ ├── index.rst +│ ├── creating_collection.rst +│ ├── structure.rst +│ ├── documenting.rst +│ ├── testing.rst +│ └── publishing.rst +└── maintaining_collections/ # Para MANTENEDORES + ├── index.rst + ├── versioning.rst + ├── deprecation.rst + └── community.rst +``` + +--- + +### 7. DOCUMENTAÇÃO DE INSTALAÇÃO MINIMAL + +**Severidade:** 🟡 MÉDIA +**Impacto:** Alto - Usuários novos têm dificuldades +**Esforço para correção:** Alto (12-16 horas) + +#### Status Atual + +`/installation_guide/` contém apenas **4 arquivos** (~13 KB total): +- `index.rst` +- `intro_installation.rst` +- `installation_distros.rst` +- `intro_configuration.rst` + +#### Conteúdo Faltante + +1. **Troubleshooting de instalação:** + - Problemas comuns por distro + - Conflitos de dependências + - Problemas de permissão + +2. **Ambientes específicos:** + - Docker/containers + - Virtual environments (venv, virtualenv) + - WSL (Windows Subsystem for Linux) + - macOS específico + - Instalação offline + +3. **Guias de upgrade:** + - Como atualizar entre versões + - Breaking changes na instalação + - Migração de configurações + +4. **Configuração pós-instalação:** + - Primeiro playbook + - Configuração inicial (ansible.cfg) + - Verificação de instalação + +#### Solução Recomendada + +**Expandir para:** + +``` +installation_guide/ +├── index.rst +├── intro_installation.rst # Existente +├── installation_distros.rst # Existente - expandir +├── intro_configuration.rst # Existente +├── troubleshooting.rst # NOVO +├── special_environments.rst # NOVO (Docker, venv, WSL) +├── upgrade_guide.rst # NOVO +├── post_installation.rst # NOVO +├── verification.rst # NOVO +└── faq_installation.rst # NOVO +``` + +--- + +### 8. DOCUMENTAÇÃO DE NETWORK ISOLADA + +**Severidade:** 🟢 BAIXA +**Impacto:** Médio - Fragmentação conceitual +**Esforço para correção:** Médio (6-10 horas) + +#### Problema + +O diretório `/network/` tem sua própria estrutura **duplicada**: + +``` +network/ +├── getting_started/ +├── user_guide/ +└── dev_guide/ +``` + +Isso replica a estrutura geral da documentação, criando uma "ilha" de conteúdo. + +#### Razões Possíveis + +- Network automation é caso de uso específico +- Audiência diferente (network engineers vs sysadmins) +- Conteúdo especializado + +#### Solução Recomendada + +**Opção 1: Integrar** (recomendado se conteúdo não for tão especializado) +``` +scenario_guides/network/ # ou os_guide/network/ +├── index.rst +├── getting_started.rst +├── platforms/ +└── advanced/ +``` + +**Opção 2: Manter separado** mas melhorar links de cross-reference +- Adicionar links claros no índice principal +- Explicar por que está separado +- Melhorar navegação entre seções + +--- + +### 9. PORTING GUIDES EXCESSIVOS + +**Severidade:** 🟢 BAIXA +**Impacto:** Baixo - Poluição visual +**Esforço para correção:** Baixo (3-4 horas) + +#### Problema + +Existem **29 porting guides** diferentes: +- Ansible 2.0, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10 +- Ansible 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 +- Ansible Core 2.11, 2.12, 2.13, 2.14, 2.15, 2.16, 2.17, 2.18, 2.19 + +#### Questões + +- Usuários raramente migram de versões muito antigas +- Guias antigos (2.0-2.5) têm relevância limitada +- Alguns guides são excessivamente grandes (1.290 linhas) +- Manutenção desnecessária de conteúdo legacy + +#### Solução Recomendada + +1. **Manter ativos:** Últimas 3-4 versões major +2. **Arquivar:** Versões 2.0-2.9 em `porting_guides/legacy/` +3. **Simplificar:** Criar matriz de migração ao invés de guias massivos +4. **Documentar:** Adicionar nota sobre suporte e EOL de versões + +--- + +## 🎯 Oportunidades de Melhoria (Priorizado) + +### PRIORIDADE 1 - CRÍTICA 🔴 + +Impacto Alto / Esforço Moderado / Execução Imediata + +#### 1.1 Eliminar Stubs e Redirecionamentos + +**Objetivo:** Remover 25+ arquivos stub de `/user_guide/` + +**Ações:** +1. Auditar todos os links que apontam para stubs +2. Atualizar referências para apontar diretamente para destino final +3. Implementar redirecionamentos HTTP 301 no Sphinx +4. Deletar arquivos stub +5. Atualizar sitemap.xml + +**Benefícios:** +- Melhor experiência de navegação +- Menos confusão para usuários +- Melhor SEO +- Redução de manutenção + +**Tempo estimado:** 4-6 horas + +--- + +#### 1.2 Consolidar User Guide + +**Objetivo:** Finalizar migração de `user_guide/` para nova estrutura + +**Ações:** +1. Verificar que TODO conteúdo foi migrado +2. Criar documento explicando a nova estrutura +3. Atualizar todos os links internos e externos conhecidos +4. Adicionar redirecionamentos permanentes +5. Remover diretório `user_guide/` após período de transição + +**Benefícios:** +- Estrutura clara e única +- Menos confusão organizacional +- Documentação mais maintainable + +**Tempo estimado:** 6-8 horas + +--- + +#### 1.3 Documentar Nova Estrutura + +**Objetivo:** Criar guia explicativo sobre organização atual + +**Ações:** +1. Criar `docs/docsite/rst/about/documentation_structure.rst` +2. Explicar cada seção principal +3. Adicionar flowchart de navegação +4. Criar "learning paths" por persona +5. Incluir FAQ sobre onde encontrar conteúdo + +**Benefícios:** +- Usuários entendem organização +- Redução de perguntas sobre onde encontrar conteúdo +- Onboarding mais rápido + +**Tempo estimado:** 3-4 horas + +--- + +### PRIORIDADE 2 - ALTA 🟡 + +Impacto Alto / Esforço Alto / Execução em 2-4 semanas + +#### 2.1 Reorganizar Documentação Windows + +**Objetivo:** Consolidar toda documentação Windows em localização única + +**Ações:** +1. Criar estrutura `/os_guide/windows/` reorganizada +2. Mover conteúdo de múltiplas localizações +3. Eliminar duplicações +4. Criar hierarquia clara (básico → avançado → dev) +5. Atualizar todos os links +6. Deletar stubs antigos + +**Benefícios:** +- Documentação Windows muito mais acessível +- Experiência coesa para usuários Windows +- Manutenção simplificada + +**Tempo estimado:** 8-12 horas + +--- + +#### 2.2 Dividir Arquivos Grandes + +**Objetivo:** Dividir arquivos com 1.000+ linhas em múltiplos arquivos temáticos + +**Arquivos alvo:** +- `playbooks_filters.rst` (2.205 linhas) → 5-6 arquivos +- `porting_guide_7.rst` (1.290 linhas) → 3-4 arquivos +- `porting_guide_12.rst` (1.523 linhas) → 3-4 arquivos + +**Ações:** +1. Analisar estrutura atual do arquivo +2. Identificar agrupamentos lógicos +3. Dividir em múltiplos arquivos +4. Criar índice com toctree +5. Atualizar referências +6. Testar build de documentação + +**Benefícios:** +- Documentação mais navegável +- Facilita encontrar informação específica +- Reduz tempo de carregamento +- Mais fácil de manter + +**Tempo estimado:** 6-10 horas por arquivo + +--- + +#### 2.3 Centralizar Documentação de Collections + +**Objetivo:** Consolidar documentação de collections em estrutura unificada + +**Ações:** +1. Mapear todo conteúdo atual sobre collections +2. Criar nova estrutura em `/collections_guide/` +3. Organizar por persona (usar/desenvolver/manter) +4. Mover conteúdo de dev_guide para nova estrutura +5. Atualizar referências +6. Deletar duplicações + +**Benefícios:** +- Usuários encontram tudo sobre collections em um lugar +- Clara separação entre usar e desenvolver +- Melhor experiência de aprendizado + +**Tempo estimado:** 10-15 horas + +--- + +#### 2.4 Expandir Installation & Troubleshooting + +**Objetivo:** Completar documentação de instalação com troubleshooting e casos especiais + +**Ações:** +1. Criar seção de troubleshooting detalhada +2. Adicionar guias para ambientes especiais (Docker, WSL, etc.) +3. Criar upgrade guides +4. Documentar configuração pós-instalação +5. Adicionar checklist de verificação +6. Criar FAQ de instalação + +**Benefícios:** +- Menos frustração de novos usuários +- Redução de issues/perguntas sobre instalação +- Onboarding mais suave + +**Tempo estimado:** 12-16 horas + +--- + +### PRIORIDADE 3 - MÉDIA 🟢 + +Impacto Médio / Esforço Moderado / Execução em 1-2 meses + +#### 3.1 Integrar Documentação de Network + +**Objetivo:** Decidir sobre separação ou integração de documentação de network + +**Ações:** +1. Avaliar audiência e necessidades +2. Decidir: integrar ou manter separado +3. Se integrar: mover para `/scenario_guides/network/` +4. Se separar: melhorar cross-references +5. Documentar decisão e razões + +**Tempo estimado:** 6-10 horas + +--- + +#### 3.2 Criar Índices por Persona + +**Objetivo:** Criar "learning paths" para diferentes tipos de usuários + +**Personas:** +- **Iniciante:** Nunca usou Ansible +- **Intermediário:** Conhece básico, quer avançar +- **Avançado:** Quer desenvolver ou customizar +- **Network Engineer:** Foco em network automation +- **Windows Admin:** Foco em ambiente Windows + +**Ações:** +1. Criar arquivo para cada persona +2. Organizar conteúdo em ordem de aprendizado +3. Incluir checkboxes de progresso +4. Adicionar tempo estimado de leitura +5. Link no índice principal + +**Benefícios:** +- Usuários seguem caminho claro +- Reduz overwhelm de iniciantes +- Facilita onboarding + +**Tempo estimado:** 8-12 horas + +--- + +#### 3.3 Expandir FAQ + +**Objetivo:** Criar FAQ abrangente e organizada + +**Ações:** +1. Coletar perguntas comuns de issues/discussions +2. Organizar por tópico +3. Adicionar respostas com links para documentação completa +4. Criar seção de troubleshooting common issues +5. Integrar com reference_appendices + +**Tempo estimado:** 6-10 horas + +--- + +#### 3.4 Melhorar Documentação de Vault + +**Objetivo:** Reorganizar e expandir documentação de segurança + +**Ações:** +1. Reorganizar em estrutura clara (básico/usar/gerenciar/desenvolver) +2. Adicionar mais exemplos práticos +3. Integrar com best practices de segurança +4. Adicionar troubleshooting +5. Documentar integração com secret managers externos + +**Tempo estimado:** 6-8 horas + +--- + +### PRIORIDADE 4 - BAIXA ⚪ + +Impacto Baixo / Esforço Variável / Execução Futura + +#### 4.1 Documentar Status de Scenario Guides + +**Objetivo:** Clarificar status e futuro de scenario_guides + +**Ações:** +1. Criar página explicando migração para collections +2. Fornecer mapa de correspondência (old → new) +3. Adicionar timeline de remoção +4. Arquivar conteúdo legacy + +**Tempo estimado:** 2-3 horas + +--- + +#### 4.2 Arquivar Porting Guides Antigos + +**Objetivo:** Limpar porting guides de versões EOL + +**Ações:** +1. Identificar versões EOL (< 2.9) +2. Mover para `/porting_guides/legacy/` +3. Manter apenas últimas 3-4 versões ativas +4. Adicionar nota sobre suporte + +**Tempo estimado:** 3-4 horas + +--- + +#### 4.3 Adicionar Novos Formatos de Conteúdo + +**Objetivo:** Diversificar formatos de documentação + +**Ideias:** +- Video tutorials (links para YouTube) +- Quick reference cards (PDFs) +- Interactive examples (Katacoda/similar) +- Troubleshooting decision trees +- Cheat sheets por tópico + +**Tempo estimado:** Ongoing, 2-4 horas por formato + +--- + +#### 4.4 Melhorar Documentação de Plugins + +**Objetivo:** Expandir documentação de module_plugin_guide + +**Ações:** +1. Criar guia para cada tipo de plugin +2. Adicionar exemplos práticos +3. Comparação entre tipos +4. Quando usar cada tipo +5. Desenvolver custom plugins + +**Tempo estimado:** 8-12 horas + +--- + +## 📅 Roadmap Sugerido + +### Próximas 2 Semanas (Sprint 1) + +**Foco:** Correções críticas e quick wins + +- ✅ Criar documento de análise (este arquivo) +- ⬜ Implementar PRIORIDADE 1.1 (Eliminar stubs) +- ⬜ Implementar PRIORIDADE 1.2 (Consolidar user_guide) +- ⬜ Implementar PRIORIDADE 1.3 (Documentar estrutura) +- ⬜ Validar todos os links internos + +**Deliverables:** +- Documentação sem stubs +- Guia de estrutura publicado +- Lista de links corrigidos + +--- + +### Próximo Mês (Sprint 2-3) + +**Foco:** Melhorias estruturais + +- ⬜ Implementar PRIORIDADE 2.1 (Windows consolidado) +- ⬜ Implementar PRIORIDADE 2.2 (Dividir arquivos grandes) +- ⬜ Implementar PRIORIDADE 2.4 (Expandir instalação) +- ⬜ Começar PRIORIDADE 2.3 (Collections) + +**Deliverables:** +- Documentação Windows unificada +- Arquivos grandes divididos +- Installation guide completo + +--- + +### Próximo Trimestre (Sprint 4-8) + +**Foco:** Melhorias de conteúdo e experiência + +- ⬜ Completar PRIORIDADE 2.3 (Collections) +- ⬜ Implementar PRIORIDADE 3.1 (Network) +- ⬜ Implementar PRIORIDADE 3.2 (Índices por persona) +- ⬜ Implementar PRIORIDADE 3.3 (FAQ expandido) +- ⬜ Implementar PRIORIDADE 3.4 (Vault) + +**Deliverables:** +- Collections guide completo +- Learning paths por persona +- FAQ abrangente + +--- + +### Próximos 6 Meses (Ongoing) + +**Foco:** Polimento e novos formatos + +- ⬜ Implementar PRIORIDADE 4 (todas) +- ⬜ Adicionar novos formatos de conteúdo +- ⬜ Melhorar continuamente baseado em feedback +- ⬜ Revisar e atualizar conteúdo existente + +--- + +## 🛠️ Ferramentas e Processos Recomendados + +### Para Validação de Links + +```bash +# Verificar links internos quebrados +nox -s "checkers(docs-build)" + +# Ou usar sphinx-build com linkcheck +sphinx-build -b linkcheck docs/docsite/rst/ build/linkcheck/ +``` + +### Para Identificar Stubs + +```bash +# Encontrar arquivos RST muito pequenos (possíveis stubs) +find docs/docsite/rst -name "*.rst" -type f -size -500c + +# Contar linhas de cada arquivo +find docs/docsite/rst -name "*.rst" -exec wc -l {} \; | sort -n +``` + +### Para Analisar Estrutura + +```bash +# Gerar árvore de diretórios +tree docs/docsite/rst -L 2 -d + +# Estatísticas de arquivos +find docs/docsite/rst -name "*.rst" | wc -l +``` + +### Para Validar Sintaxe RST + +```bash +# Verificar erros de sintaxe +nox -s "checkers(rstcheck)" + +# Build completo +nox -s make +``` + +--- + +## 📈 Métricas de Sucesso + +### Métricas Quantitativas + +| Métrica | Baseline Atual | Meta Q1 | Meta Q2 | +|---------|----------------|---------|---------| +| **Arquivos stub** | 25+ | 0 | 0 | +| **Arquivos 1000+ linhas** | 5 | 2 | 0 | +| **Diretórios deprecados** | 2 | 0 | 0 | +| **Links quebrados** | ? | 0 | 0 | +| **Tempo para encontrar info** | ? | -30% | -50% | +| **Arquivos de troubleshooting** | 3 | 10 | 15 | + +### Métricas Qualitativas + +- Feedback de usuários (survey) +- Redução de issues sobre "onde encontrar X" +- Aumento de contribuições comunitárias +- Melhor ranking em buscas (SEO) + +--- + +## 🤝 Como Contribuir com Melhorias + +### Para Contribuidores + +1. **Escolha uma task** da lista de prioridades +2. **Leia CONTRIBUTING.md** para guidelines +3. **Crie branch** com nome descritivo +4. **Faça alterações** seguindo estilo existente +5. **Teste build** com `nox -s make` +6. **Valide links** com checkers +7. **Submeta PR** com descrição clara + +### Para Mantenedores + +1. **Review PRs** com foco em clareza e precisão +2. **Mantenha tracking** de progresso do roadmap +3. **Colete feedback** de usuários +4. **Priorize** baseado em impacto +5. **Documente** decisões importantes + +--- + +## 📚 Recursos Adicionais + +### Links Úteis + +- [Guia de Contribuição](CONTRIBUTING.md) +- [Ansible Docs](https://docs.ansible.com/) +- [Sphinx RST Guide](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) +- [Documentação do Nox](https://nox.thea.codes/) + +### Referências + +- Documentação oficial do Ansible: https://docs.ansible.com/ +- Issues do repositório: https://github.com/ansible/ansible-documentation/issues +- Community discussions: https://github.com/ansible/community/discussions + +--- + +## 📝 Notas de Versão + +### v1.0 - 2025-11-22 + +- ✅ Análise inicial completa +- ✅ Identificação de 9 problemas críticos +- ✅ Priorização de 15+ oportunidades de melhoria +- ✅ Roadmap de 6 meses criado +- ✅ Métricas de sucesso definidas + +--- + +## 🎯 Próximos Passos Imediatos + +1. **HOJE:** + - ✅ Finalizar este documento + - ⬜ Criar issues no GitHub para cada prioridade + - ⬜ Apresentar para equipe de docs + +2. **ESTA SEMANA:** + - ⬜ Começar eliminação de stubs (P1.1) + - ⬜ Validar todos os links internos + - ⬜ Criar documento de estrutura (P1.3) + +3. **PRÓXIMAS 2 SEMANAS:** + - ⬜ Completar PRIORIDADE 1 (todas) + - ⬜ Começar PRIORIDADE 2.1 (Windows) + - ⬜ Coletar feedback inicial + +--- + +**Documento mantido por:** Equipe de Documentação Ansible +**Última atualização:** 2025-11-22 +**Próxima revisão:** 2025-12-06 diff --git a/DOCUMENTATION_GUIDE.md b/DOCUMENTATION_GUIDE.md new file mode 100644 index 00000000000..303bd4544d6 --- /dev/null +++ b/DOCUMENTATION_GUIDE.md @@ -0,0 +1,564 @@ +# Guia de Navegação da Documentação Ansible + +**Para usuários e contribuidores da documentação Ansible** + +Este guia explica como a documentação do Ansible está organizada e como encontrar rapidamente o que você precisa. + +--- + +## 📍 Encontrando o que Você Precisa + +### Por Persona / Experiência + +#### 🌱 **Sou INICIANTE no Ansible** + +**Comece por aqui:** + +1. **`/getting_started/`** - Primeiros passos com Ansible + - O que é Ansible e por que usar + - Conceitos fundamentais + - Seu primeiro playbook + +2. **`/installation_guide/`** - Como instalar + - Instalação por distribuição + - Configuração inicial + - Verificação da instalação + +3. **`/playbook_guide/playbooks_intro.rst`** - Introdução aos playbooks + - Estrutura básica + - Primeiros exemplos + - Melhores práticas iniciais + +**Caminho de Aprendizado Sugerido:** +``` +Installation → Getting Started → Basic Playbooks → Inventory Basics → Running Commands +``` + +**Tempo estimado:** 3-5 horas + +--- + +#### 🚀 **Tenho EXPERIÊNCIA INTERMEDIÁRIA** + +**Você provavelmente quer:** + +1. **`/playbook_guide/`** - Técnicas avançadas de playbooks + - Loops, conditionals, handlers + - Templates e variáveis + - Roles e includes + - Estratégias de execução + +2. **`/inventory_guide/`** - Gestão avançada de inventários + - Inventários dinâmicos + - Grupos e variáveis + - Padrões de organização + +3. **`/vault_guide/`** - Segurança e secrets + - Ansible Vault + - Gerenciamento de senhas + - Best practices de segurança + +4. **`/collections_guide/`** - Usando collections + - Instalando collections + - Usando módulos de collections + - Requirements files + +**Tópicos Úteis:** +- Troubleshooting playbooks → `/playbook_guide/playbooks_error_handling.rst` +- Performance tuning → `/playbook_guide/playbooks_strategies.rst` +- Testing playbooks → `/dev_guide/testing/` + +--- + +#### 🎯 **Quero DESENVOLVER/CUSTOMIZAR Ansible** + +**Documentação para desenvolvedores:** + +1. **`/dev_guide/`** - Guia completo de desenvolvimento + - Desenvolvendo módulos + - Criando plugins + - Testing e CI + - Contribuindo para o core + +2. **`/collections_guide/`** + `/dev_guide/developing_collections_*`** + - Criando collections + - Estrutura de collections + - Publicando no Galaxy + - Mantendo collections + +3. **`/module_plugin_guide/`** - Referência de módulos e plugins + - Tipos de plugins + - APIs disponíveis + - Documentando módulos + +**Recursos Adicionais:** +- API documentation → `/api/` +- Contributing guidelines → `CONTRIBUTING.md` +- Coding standards → `/dev_guide/developing_modules_best_practices.rst` + +--- + +#### 🌐 **Foco em NETWORK AUTOMATION** + +**Documentação especializada:** + +1. **`/network/getting_started/`** - Introdução à automação de rede +2. **`/network/user_guide/`** - Guias de uso +3. **`/network/dev_guide/`** - Desenvolvimento para rede + +**Nota:** A documentação de network está organizada separadamente devido à natureza especializada do conteúdo. + +--- + +#### 🖥️ **Trabalho com WINDOWS** + +**Tudo sobre Windows:** + +1. **`/os_guide/intro_windows.rst`** - Introdução ao Ansible para Windows +2. **`/os_guide/windows_setup.rst`** - Configuração de hosts Windows +3. **`/os_guide/windows_winrm.rst`** - Configuração WinRM +4. **`/os_guide/windows_faq.rst`** - FAQ Windows + +**Desenvolvimento:** +- `/dev_guide/developing_modules_general_windows.rst` - Módulos Windows + +--- + +### Por Tarefa Específica + +#### 📦 "Preciso instalar o Ansible" +→ **`/installation_guide/`** + +#### 🎭 "Quero escrever playbooks" +→ **`/playbook_guide/`** + +#### 📋 "Preciso gerenciar inventários" +→ **`/inventory_guide/`** + +#### 🔐 "Quero usar Vault para secrets" +→ **`/vault_guide/`** + +#### 🧩 "Quero usar/criar collections" +→ **`/collections_guide/`** (usar) + **`/dev_guide/developing_collections_*`** (criar) + +#### ⚡ "Quero entender os comandos CLI" +→ **`/command_guide/`** + +#### 🐛 "Meu playbook não funciona (troubleshooting)" +→ **`/playbook_guide/playbooks_error_handling.rst`** +→ **`/reference_appendices/faq.rst`** + +#### 📚 "Quero migrar de versão X para Y" +→ **`/porting_guides/porting_guide_X.rst`** + +#### 💡 "Quero dicas e truques" +→ **`/tips_tricks/`** + +#### 🌟 "Quero publicar no Galaxy" +→ **`/galaxy/`** + +#### 🤝 "Quero contribuir para o projeto" +→ **`CONTRIBUTING.md`** +→ **`/community/`** + +--- + +## 🗂️ Estrutura de Diretórios Explicada + +### Documentação para USUÁRIOS + +| Diretório | Propósito | Quando Usar | +|-----------|-----------|-------------| +| **`getting_started/`** | Primeiros passos | Nunca usei Ansible | +| **`getting_started_ee/`** | Execution Environments | Trabalho com containers/EE | +| **`installation_guide/`** | Instalação | Preciso instalar/configurar | +| **`playbook_guide/`** | Playbooks (principal) | Escrever/melhorar playbooks | +| **`inventory_guide/`** | Inventários | Gerenciar hosts | +| **`command_guide/`** | Comandos CLI | Usar ansible, ansible-playbook | +| **`vault_guide/`** | Segurança/Vault | Proteger secrets | +| **`collections_guide/`** | Usar collections | Instalar/usar collections | +| **`os_guide/`** | SO específico | Windows, BSD, etc. | +| **`network/`** | Network automation | Automação de rede | +| **`tips_tricks/`** | Dicas práticas | Otimizar workflow | + +### Documentação para DESENVOLVEDORES + +| Diretório | Propósito | Quando Usar | +|-----------|-----------|-------------| +| **`dev_guide/`** | Desenvolvimento | Criar módulos/plugins | +| **`module_plugin_guide/`** | Referência | Entender tipos de plugins | +| **`api/`** | API do Ansible | Integrar programaticamente | +| **`community/`** | Contribuição | Contribuir para projeto | + +### Documentação de REFERÊNCIA + +| Diretório | Propósito | Quando Usar | +|-----------|-----------|-------------| +| **`reference_appendices/`** | Referências gerais | Lookup rápido | +| **`porting_guides/`** | Migração de versões | Atualizar versão | +| **`galaxy/`** | Ansible Galaxy | Publicar/usar Galaxy | +| **`roadmap/`** | Roadmap do projeto | Acompanhar desenvolvimento | + +### ⚠️ Diretórios LEGADOS (Não Use) + +| Diretório | Status | Use Em Vez | +|-----------|--------|------------| +| **`user_guide/`** | **DEPRECIADO** | `playbook_guide/`, `inventory_guide/`, etc. | +| **`scenario_guides/`** | **DESCONTINUADO** | Collections específicas | + +--- + +## 🧭 Fluxo de Navegação Típico + +### Para Iniciante + +```mermaid +flowchart TD + A[📚 Início] --> B[📦 Installation Guide] + B --> C[🌱 Getting Started] + C --> D[🎭 Playbook Guide - Intro] + D --> E[📋 Inventory Guide - Basics] + E --> F[⚡ Command Guide] + F --> G[💡 Tips & Tricks] +``` + +### Para Usuário Intermediário + +```mermaid +flowchart TD + A[💼 Tarefa Específica] --> B{Tipo?} + B -->|Playbook| C[🎭 Playbook Guide] + B -->|Inventário| D[📋 Inventory Guide] + B -->|Segurança| E[🔐 Vault Guide] + B -->|Collections| F[📦 Collections Guide] + C --> G[💡 Tips & Tricks] + D --> G + E --> G + F --> G +``` + +### Para Desenvolvedor + +```mermaid +flowchart TD + A[🛠️ Desenvolvimento] --> B{O que?} + B -->|Módulo| C[💻 Dev Guide - Modules] + B -->|Plugin| D[💻 Dev Guide - Plugins] + B -->|Collection| E[📦 Developing Collections] + C --> F[✅ Testing] + D --> F + E --> F + F --> G[📤 Publicar/Contribuir] +``` + +--- + +## 🔍 Como Pesquisar Eficientemente + +### Pesquisa Local com Grep + +```bash +# Procurar por termo específico +nox -s grep -- "termo_de_busca" + +# Procurar em arquivos RST +grep -r "termo" docs/docsite/rst/ --include="*.rst" + +# Procurar por função/módulo +grep -r "win_ping" docs/docsite/rst/ +``` + +### Pesquisa na Documentação Online + +- **Site oficial:** https://docs.ansible.com/ +- **Busca do site:** Use a barra de pesquisa integrada +- **Google:** `site:docs.ansible.com termo_de_busca` + +### Índices Úteis + +- **Índice Geral:** `/ansible_index.rst` +- **Índice Core:** `/core_index.rst` +- **Índice por Seção:** `{seção}/index.rst` + +--- + +## 📖 Arquivos Essenciais + +### Para Contribuidores + +| Arquivo | Descrição | +|---------|-----------| +| **`README.md`** | Como contribuir com a documentação | +| **`CONTRIBUTING.md`** | Políticas de contribuição | +| **`MAINTAINERS.md`** | Informações de mantenedores | +| **`DCO`** | Developer Certificate of Origin | + +### Para Desenvolvimento Local + +| Arquivo | Descrição | +|---------|-----------| +| **`noxfile.py`** | Configuração de testes e builds | +| **`docs/docsite/rst/conf.py`** | Configuração do Sphinx | +| **`.readthedocs.yaml`** | Configuração Read the Docs | + +--- + +## 🚀 Quick Start: Casos de Uso Comuns + +### Caso 1: "Nunca usei Ansible, por onde começar?" + +```bash +1. Leia: /installation_guide/intro_installation.rst +2. Leia: /getting_started/get_started_ansible.rst +3. Leia: /getting_started/get_started_playbook.rst +4. Pratique: Execute exemplos do /examples/ +5. Avance: /playbook_guide/playbooks_intro.rst +``` + +--- + +### Caso 2: "Quero escrever um playbook para configurar servidores web" + +```bash +1. Conceitos básicos: /playbook_guide/playbooks_intro.rst +2. Variáveis: /playbook_guide/playbooks_variables.rst +3. Templates: /playbook_guide/playbooks_templating.rst +4. Handlers: /playbook_guide/playbooks_handlers.rst +5. Roles (recomendado): /playbook_guide/playbooks_reuse_roles.rst +6. Exemplo prático: /examples/ +``` + +--- + +### Caso 3: "Preciso criar um módulo customizado" + +```bash +1. Introdução: /dev_guide/developing_modules_general.rst +2. Estrutura: /dev_guide/developing_modules_documenting.rst +3. Best practices: /dev_guide/developing_modules_best_practices.rst +4. Testing: /dev_guide/testing/ +5. Exemplo: Veja módulos existentes no ansible/ansible +``` + +--- + +### Caso 4: "Quero usar Ansible com Windows" + +```bash +1. Introdução: /os_guide/intro_windows.rst +2. Setup: /os_guide/windows_setup.rst +3. WinRM: /os_guide/windows_winrm.rst +4. Módulos: /os_guide/windows_usage.rst +5. FAQ: /os_guide/windows_faq.rst +``` + +--- + +### Caso 5: "Quero migrar de Ansible 10 para 11" + +```bash +1. Leia: /porting_guides/porting_guide_11.rst +2. Verifique breaking changes +3. Teste em ambiente de dev +4. Atualize playbooks conforme necessário +``` + +--- + +## ❓ FAQ sobre Navegação + +### P: Por que existem duas estruturas (user_guide e playbook_guide)? + +**R:** O `user_guide/` está **depreciado** e foi reorganizado em guias mais específicos (`playbook_guide/`, `inventory_guide/`, `command_guide/`). Sempre use os novos guias. Os arquivos antigos contêm apenas redirecionamentos e serão removidos no futuro. + +### P: Onde encontro documentação de módulos específicos? + +**R:** Módulos estão documentados no repositório `ansible/ansible`. A documentação aqui foca em **como usar** módulos, não documentação de módulos individuais. Use `ansible-doc nome_modulo` para documentação de módulo específico. + +### P: Scenario guides está descontinuado? + +**R:** Sim, scenario guides estão sendo **migrados para collections**. Para conteúdo atualizado, consulte as collections relevantes (ex: `amazon.aws`, `community.docker`). + +### P: Por que a documentação de network está separada? + +**R:** Network automation tem audiência e requisitos específicos. A separação facilita navegação para network engineers e permite foco em conteúdo especializado. + +### P: Onde encontro exemplos práticos? + +**R:** Exemplos estão em: +- `/examples/` (raiz do repositório) +- Dentro de cada guia (exemplos inline) +- Collections no Galaxy (com exemplos completos) + +### P: Como contribuo com a documentação? + +**R:** Leia `README.md` e `CONTRIBUTING.md` na raiz do repositório. Use `nox` para validar suas mudanças antes de submeter PR. + +--- + +## 🎓 Learning Paths Recomendados + +### Path 1: Fundamentos (5-8 horas) + +``` +□ Installation Guide +□ Getting Started +□ Basic Playbook Concepts +□ Inventory Basics +□ Running Your First Playbook +□ Variables and Facts +□ Conditionals and Loops +``` + +### Path 2: Intermediário (10-15 horas) + +``` +□ Advanced Playbooks +□ Roles and Includes +□ Templates (Jinja2) +□ Handlers and Notifications +□ Error Handling +□ Ansible Vault +□ Collections Basics +□ Best Practices +``` + +### Path 3: Avançado (15-20 horas) + +``` +□ Developing Modules +□ Creating Plugins +□ Creating Collections +□ Testing Strategies +□ Performance Tuning +□ CI/CD Integration +□ Contributing to Ansible +``` + +### Path 4: Network Engineer (8-12 horas) + +``` +□ Network Getting Started +□ Network Platforms +□ Network Modules +□ Network Best Practices +□ Backup and Restore +□ Advanced Network Automation +``` + +### Path 5: Windows Admin (6-10 horas) + +``` +□ Windows Introduction +□ Windows Setup +□ WinRM Configuration +□ Windows Modules +□ Windows Best Practices +□ Troubleshooting Windows +``` + +--- + +## 📊 Mapa Visual da Documentação + +``` +ansible-documentation/ +│ +├── 🌱 INÍCIO (Novos Usuários) +│ ├── installation_guide/ +│ ├── getting_started/ +│ └── getting_started_ee/ +│ +├── 📚 USO DIÁRIO (Usuários Regulares) +│ ├── playbook_guide/ ⭐ PRINCIPAL +│ ├── inventory_guide/ +│ ├── command_guide/ +│ ├── vault_guide/ +│ └── collections_guide/ +│ +├── 🎯 ESPECIALIZADO (Casos Específicos) +│ ├── os_guide/ (Windows, BSD, etc.) +│ ├── network/ (Network Automation) +│ └── tips_tricks/ +│ +├── 💻 DESENVOLVIMENTO (Desenvolvedores) +│ ├── dev_guide/ ⭐ PRINCIPAL +│ ├── module_plugin_guide/ +│ ├── api/ +│ └── community/ +│ +├── 📖 REFERÊNCIA (Consulta Rápida) +│ ├── reference_appendices/ +│ ├── porting_guides/ +│ ├── galaxy/ +│ └── roadmap/ +│ +└── ⚠️ LEGADO (Não Use) + ├── user_guide/ ❌ DEPRECIADO + └── scenario_guides/ ❌ DESCONTINUADO +``` + +--- + +## 🔗 Links Úteis + +- **Documentação Online:** https://docs.ansible.com/ +- **Repositório Ansible Core:** https://github.com/ansible/ansible +- **Ansible Galaxy:** https://galaxy.ansible.com/ +- **Community Forum:** https://forum.ansible.com/ +- **Issues:** https://github.com/ansible/ansible-documentation/issues +- **Mailing List:** https://groups.google.com/group/ansible-project + +--- + +## 📞 Precisa de Ajuda? + +### Para Perguntas sobre Uso + +1. **FAQ:** `/reference_appendices/faq.rst` +2. **Forum:** https://forum.ansible.com/ +3. **IRC:** #ansible no Libera.Chat +4. **Mailing List:** ansible-project@googlegroups.com + +### Para Bugs/Issues de Documentação + +1. **GitHub Issues:** https://github.com/ansible/ansible-documentation/issues +2. Use template adequado +3. Inclua informações de contexto + +### Para Contribuições + +1. Leia **`CONTRIBUTING.md`** +2. Siga guidelines de estilo +3. Teste com `nox` +4. Submeta PR com descrição clara + +--- + +## 📝 Como Este Guia Está Organizado + +Este guia usa os seguintes ícones para facilitar navegação: + +- 📦 Instalação e setup +- 🌱 Conteúdo para iniciantes +- 🚀 Conteúdo intermediário +- 🎯 Conteúdo avançado +- 💻 Desenvolvimento +- 🌐 Network automation +- 🖥️ Windows +- 🔐 Segurança +- 📚 Referência +- ⚠️ Atenção/Aviso +- ❌ Depreciado/Não use +- ✅ Recomendado +- ⭐ Essencial/Importante + +--- + +**Última atualização:** 2025-11-22 +**Versão do guia:** 1.0 +**Feedback:** https://github.com/ansible/ansible-documentation/issues + +--- + +**💡 Dica:** Marque este guia nos favoritos para referência rápida durante seu aprendizado! diff --git a/IMPROVEMENT_ROADMAP.md b/IMPROVEMENT_ROADMAP.md new file mode 100644 index 00000000000..a74ac14177d --- /dev/null +++ b/IMPROVEMENT_ROADMAP.md @@ -0,0 +1,611 @@ +# Roadmap de Melhorias da Documentação Ansible + +**Status:** Em Planejamento +**Última Atualização:** 2025-11-22 +**Versão:** 1.0 + +Este documento apresenta o roadmap executivo para melhorias da documentação do Ansible nos próximos 6 meses. + +--- + +## 🎯 Visão Geral + +### Objetivo Principal +Consolidar e melhorar a documentação do Ansible, eliminando redundâncias, completando lacunas e facilitando navegação para usuários de todos os níveis. + +### Metas Mensuráveis +- ✅ Eliminar 100% dos arquivos stub (25+ arquivos) +- ✅ Reduzir arquivos com 1000+ linhas em 60% +- ✅ Completar documentação de instalação e troubleshooting +- ✅ Consolidar documentação fragmentada (Windows, Collections) +- ✅ Criar learning paths para 5 personas diferentes + +--- + +## 📅 Timeline Executivo + +``` +Sprint 1-2 (Semanas 1-4) → Correções Críticas +Sprint 3-4 (Semanas 5-8) → Consolidação Estrutural +Sprint 5-8 (Semanas 9-16) → Expansão de Conteúdo +Sprint 9-12 (Semanas 17-24) → Polimento e Novos Formatos +``` + +--- + +## 🚀 FASE 1: Correções Críticas (Semanas 1-4) + +### Sprint 1 (Semanas 1-2) + +**Objetivo:** Eliminar problemas mais urgentes que afetam experiência do usuário + +#### Tarefas + +**Semana 1** +- [ ] ✅ Criar documentos de análise e guias *(CONCLUÍDO)* +- [ ] Auditar todos os links internos que apontam para stubs +- [ ] Criar lista completa de arquivos stub para remoção +- [ ] Atualizar links internos para apontar diretamente ao destino +- [ ] Configurar redirecionamentos HTTP 301 no `conf.py` + +**Semana 2** +- [ ] Deletar arquivos stub após validação +- [ ] Testar build completo da documentação +- [ ] Validar todos os links internos (zero broken links) +- [ ] Criar documento explicativo sobre nova estrutura em `/about/` +- [ ] Adicionar avisos de depreciação em `user_guide/index.rst` + +**Entregáveis Sprint 1:** +- ✅ Documentação sem stubs +- ✅ Guia de estrutura publicado +- ✅ Zero broken links +- ✅ Avisos de depreciação claros + +**Responsável:** Equipe de Documentação +**Review:** Final da semana 2 + +--- + +### Sprint 2 (Semanas 3-4) + +**Objetivo:** Finalizar consolidação da estrutura user_guide + +#### Tarefas + +**Semana 3** +- [ ] Verificar migração completa de conteúdo de `user_guide/` +- [ ] Criar página de mapeamento (old path → new path) +- [ ] Atualizar índice principal com estrutura clara +- [ ] Adicionar breadcrumbs de navegação +- [ ] Documentar decisões de arquitetura + +**Semana 4** +- [ ] Implementar redirecionamentos permanentes +- [ ] Adicionar nota de depreciação em todas as páginas antigas +- [ ] Criar timeline de remoção (ex: após Ansible 13) +- [ ] Comunicar mudanças para comunidade +- [ ] Atualizar links em repos externos conhecidos + +**Entregáveis Sprint 2:** +- ✅ User guide completamente consolidado +- ✅ Mapeamento de paths publicado +- ✅ Comunicação para comunidade enviada + +**Responsável:** Equipe de Documentação + Core Team +**Review:** Final da semana 4 + +--- + +## 🏗️ FASE 2: Consolidação Estrutural (Semanas 5-8) + +### Sprint 3 (Semanas 5-6) + +**Objetivo:** Consolidar documentação Windows e dividir arquivos grandes + +#### Tarefas + +**Semana 5 - Windows Documentation** +- [ ] Criar nova estrutura `/os_guide/windows/` +- [ ] Mapear todo conteúdo Windows existente +- [ ] Mover conteúdo de `/user_guide/windows_*` +- [ ] Mover conteúdo de `/dev_guide/developing_modules_general_windows.rst` +- [ ] Eliminar duplicações +- [ ] Criar hierarquia clara (básico → avançado → dev) + +**Semana 6 - Dividir Arquivos Grandes** +- [ ] Dividir `playbooks_filters.rst` (2.205 linhas) em 5-6 arquivos + - `playbooks_filters.rst` (índice) + - `playbooks_filters_basic.rst` + - `playbooks_filters_text.rst` + - `playbooks_filters_list.rst` + - `playbooks_filters_math.rst` + - `playbooks_filters_network.rst` +- [ ] Atualizar toctree e referências +- [ ] Testar build + +**Entregáveis Sprint 3:** +- ✅ Documentação Windows unificada em `/os_guide/windows/` +- ✅ `playbooks_filters.rst` dividido e organizado +- ✅ Build testado e funcionando + +**Responsável:** Equipe de Documentação +**Review:** Final da semana 6 + +--- + +### Sprint 4 (Semanas 7-8) + +**Objetivo:** Expandir installation guide e começar consolidação de collections + +#### Tarefas + +**Semana 7 - Installation Guide** +- [ ] Criar `installation_guide/troubleshooting.rst` +- [ ] Criar `installation_guide/special_environments.rst` (Docker, venv, WSL) +- [ ] Criar `installation_guide/upgrade_guide.rst` +- [ ] Criar `installation_guide/post_installation.rst` +- [ ] Criar `installation_guide/verification.rst` +- [ ] Criar `installation_guide/faq_installation.rst` +- [ ] Atualizar índice + +**Semana 8 - Collections (Início)** +- [ ] Mapear toda documentação sobre collections +- [ ] Criar nova estrutura em `/collections_guide/` + - `using_collections/` + - `developing_collections/` + - `maintaining_collections/` +- [ ] Começar migração de conteúdo de `/dev_guide/developing_collections_*` + +**Entregáveis Sprint 4:** +- ✅ Installation guide completo e abrangente +- ✅ Nova estrutura de collections criada +- ✅ 50% do conteúdo de collections migrado + +**Responsável:** Equipe de Documentação +**Review:** Final da semana 8 + +--- + +## 📚 FASE 3: Expansão de Conteúdo (Semanas 9-16) + +### Sprint 5 (Semanas 9-10) + +**Objetivo:** Completar consolidação de collections e dividir porting guides + +#### Tarefas + +**Semana 9 - Collections (Conclusão)** +- [ ] Completar migração de todo conteúdo sobre collections +- [ ] Organizar por persona (usar/desenvolver/manter) +- [ ] Atualizar referências em toda documentação +- [ ] Deletar duplicações +- [ ] Criar exemplos práticos + +**Semana 10 - Porting Guides** +- [ ] Dividir `porting_guide_7.rst` (1.290 linhas) +- [ ] Dividir `porting_guide_12.rst` (1.523 linhas) +- [ ] Organizar por categoria (Breaking Changes, Deprecations, New Features) +- [ ] Mover guides para versão <2.9 para `/porting_guides/legacy/` +- [ ] Atualizar índice + +**Entregáveis Sprint 5:** +- ✅ Documentação de collections completamente consolidada +- ✅ Porting guides divididos e organizados +- ✅ Guides legados arquivados + +**Responsável:** Equipe de Documentação +**Review:** Final da semana 10 + +--- + +### Sprint 6 (Semanas 11-12) + +**Objetivo:** Criar learning paths e melhorar navegação + +#### Tarefas + +**Semana 11 - Learning Paths** +- [ ] Criar learning path para Iniciantes +- [ ] Criar learning path para Intermediários +- [ ] Criar learning path para Avançados/Desenvolvedores +- [ ] Criar learning path para Network Engineers +- [ ] Criar learning path para Windows Admins +- [ ] Adicionar checkboxes de progresso +- [ ] Adicionar tempo estimado + +**Semana 12 - Melhorias de Navegação** +- [ ] Criar índices por persona +- [ ] Adicionar breadcrumbs em todas as páginas +- [ ] Melhorar sidebar de navegação +- [ ] Criar mapa visual da documentação +- [ ] Adicionar "Related Topics" em páginas principais + +**Entregáveis Sprint 6:** +- ✅ 5 learning paths completos e publicados +- ✅ Navegação melhorada com breadcrumbs +- ✅ Índices por persona funcionais + +**Responsável:** Equipe de Documentação + UX +**Review:** Final da semana 12 + +--- + +### Sprint 7 (Semanas 13-14) + +**Objetivo:** Expandir FAQ e melhorar Vault documentation + +#### Tarefas + +**Semana 13 - FAQ** +- [ ] Coletar perguntas comuns de issues/discussions +- [ ] Organizar FAQ por tópico +- [ ] Adicionar seção de Common Issues +- [ ] Adicionar seção de Troubleshooting +- [ ] Integrar com reference_appendices +- [ ] Adicionar links para documentação completa + +**Semana 14 - Vault Guide** +- [ ] Reorganizar em estrutura clara (básico/usar/gerenciar/desenvolver) +- [ ] Adicionar mais exemplos práticos +- [ ] Integrar com security best practices +- [ ] Adicionar troubleshooting section +- [ ] Documentar integração com secret managers externos + +**Entregáveis Sprint 7:** +- ✅ FAQ abrangente e organizada +- ✅ Vault documentation reorganizada e expandida +- ✅ Seção de troubleshooting completa + +**Responsável:** Equipe de Documentação +**Review:** Final da semana 14 + +--- + +### Sprint 8 (Semanas 15-16) + +**Objetivo:** Integrar/melhorar documentação de network + +#### Tarefas + +**Semana 15 - Análise e Decisão** +- [ ] Avaliar audiência e necessidades de network docs +- [ ] Decidir: integrar ou manter separado +- [ ] Documentar decisão e razões +- [ ] Comunicar para comunidade network + +**Semana 16 - Implementação** +- [ ] Se integrar: mover para `/scenario_guides/network/` +- [ ] Se separar: melhorar cross-references +- [ ] Adicionar links claros no índice principal +- [ ] Explicar por que está separado (se aplicável) +- [ ] Melhorar navegação entre seções + +**Entregáveis Sprint 8:** +- ✅ Documentação de network integrada ou melhorada +- ✅ Decisão documentada e comunicada +- ✅ Cross-references funcionais + +**Responsável:** Equipe de Documentação + Network Team +**Review:** Final da semana 16 + +--- + +## 🎨 FASE 4: Polimento e Novos Formatos (Semanas 17-24) + +### Sprint 9 (Semanas 17-18) + +**Objetivo:** Documentar scenario guides e arquivar conteúdo legacy + +#### Tarefas + +**Semana 17 - Scenario Guides** +- [ ] Criar página explicando migração para collections +- [ ] Fornecer mapa de correspondência (old guide → new collection) +- [ ] Adicionar timeline de remoção +- [ ] Arquivar conteúdo legacy +- [ ] Adicionar avisos claros em cada guia descontinuado + +**Semana 18 - Plugins Documentation** +- [ ] Criar guia para cada tipo de plugin +- [ ] Adicionar exemplos práticos +- [ ] Comparação entre tipos de plugins +- [ ] Quando usar cada tipo +- [ ] Desenvolver custom plugins + +**Entregáveis Sprint 9:** +- ✅ Status de scenario guides clarificado +- ✅ Mapa de migração publicado +- ✅ Plugin documentation expandida + +**Responsável:** Equipe de Documentação +**Review:** Final da semana 18 + +--- + +### Sprint 10 (Semanas 19-20) + +**Objetivo:** Adicionar novos formatos de conteúdo + +#### Tarefas + +**Semana 19 - Quick References** +- [ ] Criar quick reference cards (PDFs) + - Ansible Commands Cheat Sheet + - Playbook Syntax Quick Reference + - Module Common Parameters + - Best Practices Checklist +- [ ] Criar troubleshooting decision trees +- [ ] Criar flowcharts para processos comuns + +**Semana 20 - Interactive Content** +- [ ] Curar lista de video tutorials (YouTube) +- [ ] Criar links para interactive examples +- [ ] Adicionar "Try It Yourself" sections +- [ ] Criar exemplos executáveis (se possível) + +**Entregáveis Sprint 10:** +- ✅ 4-5 quick reference PDFs +- ✅ Decision trees para troubleshooting +- ✅ Lista curada de video tutorials +- ✅ Interactive examples + +**Responsável:** Equipe de Documentação + Community +**Review:** Final da semana 20 + +--- + +### Sprint 11 (Semanas 21-22) + +**Objetivo:** Revisar e atualizar conteúdo existente + +#### Tarefas + +**Semana 21 - Content Audit** +- [ ] Revisar top 50 páginas mais acessadas +- [ ] Identificar conteúdo desatualizado +- [ ] Atualizar exemplos para versões atuais +- [ ] Verificar screenshots (se aplicável) +- [ ] Atualizar links externos + +**Semana 22 - Best Practices Update** +- [ ] Revisar best practices em todas as seções +- [ ] Atualizar para refletir práticas atuais +- [ ] Adicionar exemplos modernos +- [ ] Incluir anti-patterns comuns +- [ ] Atualizar security recommendations + +**Entregáveis Sprint 11:** +- ✅ Top 50 páginas revisadas e atualizadas +- ✅ Best practices atualizadas +- ✅ Conteúdo desatualizado identificado e corrigido + +**Responsável:** Equipe de Documentação + SMEs +**Review:** Final da semana 22 + +--- + +### Sprint 12 (Semanas 23-24) + +**Objetivo:** Finalização e lançamento + +#### Tarefas + +**Semana 23 - Testing & Validation** +- [ ] Build completo da documentação +- [ ] Validação de todos os links (interno e externo) +- [ ] Teste de navegação (UX testing) +- [ ] Verificação de spelling e gramática +- [ ] Review final por stakeholders + +**Semana 24 - Launch & Communication** +- [ ] Publicar todas as mudanças +- [ ] Criar blog post anunciando melhorias +- [ ] Comunicar para mailing lists +- [ ] Apresentar em community meeting +- [ ] Coletar feedback inicial + +**Entregáveis Sprint 12:** +- ✅ Documentação completamente revisada e publicada +- ✅ Blog post de lançamento +- ✅ Comunicação para comunidade +- ✅ Plano de coleta de feedback + +**Responsável:** Equipe de Documentação + Marketing +**Review:** Final da semana 24 + +--- + +## 📊 Métricas e KPIs + +### Métricas de Progresso + +| Métrica | Baseline | Q1 Target | Q2 Target | Status | +|---------|----------|-----------|-----------|--------| +| Arquivos stub | 25+ | 0 | 0 | 🟡 Em Progresso | +| Arquivos 1000+ linhas | 5 | 2 | 0 | ⚪ Pendente | +| Diretórios deprecados | 2 | 0 | 0 | ⚪ Pendente | +| Links quebrados | ? | 0 | 0 | ⚪ Pendente | +| Seções de troubleshooting | 3 | 10 | 15 | ⚪ Pendente | +| Learning paths | 0 | 5 | 5 | ⚪ Pendente | +| Quick references | 0 | 4 | 8 | ⚪ Pendente | + +### Métricas de Qualidade + +**A serem medidas trimestralmente:** + +- User satisfaction score (survey) +- Time to find information (UX testing) +- Documentation issues reported +- Community contributions +- Page views e engagement + +### Critérios de Sucesso + +✅ **Completo:** +- [ ] Zero arquivos stub +- [ ] Zero links quebrados +- [ ] Todas as seções principais completas +- [ ] Learning paths para 5 personas +- [ ] User satisfaction > 4.0/5.0 + +--- + +## 👥 Responsabilidades + +### Core Documentation Team +- Execução de tasks +- Reviews de PRs +- Manutenção de roadmap +- Coordenação com stakeholders + +### Subject Matter Experts (SMEs) +- Review técnico de conteúdo +- Validação de best practices +- Input sobre prioridades + +### Community Contributors +- Contribuições de conteúdo +- Feedback e testing +- Translation (se aplicável) + +### UX Team +- Design de navegação +- User testing +- Feedback de usabilidade + +--- + +## 🔄 Processo de Revisão + +### Weekly Check-ins +- Toda segunda-feira, 15:00 UTC +- Review de progresso da semana anterior +- Planejamento da semana atual +- Identificação de blockers + +### Sprint Reviews +- Final de cada sprint (2 semanas) +- Demo de entregáveis +- Retrospectiva +- Ajustes de roadmap se necessário + +### Monthly Stakeholder Update +- Primeira sexta-feira do mês +- Apresentação de progresso +- Discussão de decisões importantes +- Coleta de feedback + +--- + +## 🚧 Riscos e Mitigações + +### Risco 1: Sobrecarga da Equipe +**Probabilidade:** Média +**Impacto:** Alto +**Mitigação:** +- Priorizar tasks críticas +- Envolver comunidade +- Ajustar timeline se necessário + +### Risco 2: Mudanças no Core Ansible +**Probabilidade:** Alta +**Impacto:** Médio +**Mitigação:** +- Coordenação próxima com core team +- Buffer time em sprints +- Documentação modular para fácil atualização + +### Risco 3: Falta de Feedback da Comunidade +**Probabilidade:** Baixa +**Impacto:** Alto +**Mitigação:** +- Comunicação proativa +- Surveys regulares +- Canais múltiplos de feedback + +### Risco 4: Breaking Changes na Estrutura +**Probabilidade:** Baixa +**Impacto:** Alto +**Mitigação:** +- Redirecionamentos permanentes +- Período de transição (6+ meses) +- Comunicação clara e antecipada + +--- + +## 📢 Comunicação + +### Canais de Comunicação + +**Para Equipe:** +- Slack: #docs-team +- GitHub: Project board +- Weekly meetings + +**Para Comunidade:** +- Mailing list: ansible-project@googlegroups.com +- Forum: https://forum.ansible.com/ +- Blog: Ansible.com/blog +- Twitter: @ansible + +### Momentos de Comunicação + +| Marco | Audiência | Canal | +|-------|-----------|-------| +| Início do projeto | Comunidade | Blog post, mailing list | +| Final FASE 1 | Comunidade | Forum post | +| Final FASE 2 | Comunidade + Stakeholders | Blog post | +| Final FASE 3 | Todos | Blog post, apresentação | +| Lançamento final | Todos | Blog post, social media, email | + +--- + +## 📝 Próximos Passos Imediatos + +### Esta Semana +1. ✅ Finalizar documentos de análise e guias +2. [ ] Criar issues no GitHub para cada task de Sprint 1 +3. [ ] Apresentar roadmap para core team +4. [ ] Obter buy-in dos stakeholders +5. [ ] Começar Sprint 1 + +### Próximas 2 Semanas +1. [ ] Completar Sprint 1 (eliminação de stubs) +2. [ ] Validar todos os links +3. [ ] Criar documento de estrutura +4. [ ] Comunicar para comunidade + +### Próximo Mês +1. [ ] Completar FASE 1 (Correções Críticas) +2. [ ] Começar FASE 2 (Consolidação Estrutural) +3. [ ] Primeira coleta de feedback +4. [ ] Ajustar roadmap baseado em feedback + +--- + +## 🔗 Recursos Relacionados + +- [Análise Detalhada](DOCUMENTATION_ANALYSIS.md) +- [Guia de Navegação](DOCUMENTATION_GUIDE.md) +- [Contributing Guidelines](CONTRIBUTING.md) +- [GitHub Project Board](https://github.com/ansible/ansible-documentation/projects) + +--- + +## 📅 Histórico de Versões + +### v1.0 - 2025-11-22 +- ✅ Roadmap inicial criado +- ✅ 4 fases definidas (24 semanas) +- ✅ Métricas e KPIs estabelecidos +- ✅ Responsabilidades atribuídas +- ✅ Riscos identificados + +--- + +**Mantido por:** Equipe de Documentação Ansible +**Última atualização:** 2025-11-22 +**Próxima revisão:** 2025-12-06 (Bi-weekly) + +**Status do Projeto:** 🟢 On Track | 🟡 At Risk | 🔴 Delayed +**Status Atual:** 🟢 On Track (Fase de Planejamento) diff --git a/README.md b/README.md index ae2ba67ce8a..247cdb7d8ba 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,12 @@ This repository holds the ReStructuredText (RST) source, and other files, for us > Documentation for modules and plugins that are officially supported by the Ansible Core engineering team is available in the [`ansible/ansible`](https://github.com/ansible/ansible) repository. +## 📚 Documentation Resources + +- **[Documentation Guide](DOCUMENTATION_GUIDE.md)** - How to navigate and find what you need +- **[Documentation Analysis](DOCUMENTATION_ANALYSIS.md)** - Current structure analysis and improvement opportunities +- **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute to documentation + ## Verifying your pull request We welcome all contributions to Ansible community documentation. @@ -140,6 +146,28 @@ To upgrade a single dependency, for instance when adjusting constraints on a pac nox -s pip-compile -- --upgrade-package ``` +## Understanding the Documentation Structure + +The documentation is organized into several main sections: + +- **`getting_started/`** - For new Ansible users +- **`installation_guide/`** - Installation and setup +- **`playbook_guide/`** - Writing and managing playbooks (main user guide) +- **`inventory_guide/`** - Managing inventories +- **`command_guide/`** - CLI tools reference +- **`vault_guide/`** - Security and Ansible Vault +- **`collections_guide/`** - Using and developing collections +- **`dev_guide/`** - Development documentation +- **`os_guide/`** - OS-specific guides (Windows, BSD, etc.) +- **`network/`** - Network automation documentation + +For a complete navigation guide, see [DOCUMENTATION_GUIDE.md](DOCUMENTATION_GUIDE.md). + +### ⚠️ Deprecated Sections + +- **`user_guide/`** - Deprecated in favor of the new structure above (contains only redirects) +- **`scenario_guides/`** - Being migrated to collections + ## Creating release tags When a tag is created in the [`ansible/ansible`](https://github.com/ansible/ansible) repository for a release or release candidate, a corresponding tag should be created in this `ansible-documentation` repository. diff --git a/STUB_FILES_INVENTORY.md b/STUB_FILES_INVENTORY.md new file mode 100644 index 00000000000..b9f4ccc4865 --- /dev/null +++ b/STUB_FILES_INVENTORY.md @@ -0,0 +1,534 @@ +# Inventário de Arquivos Stub para Remoção + +**Data:** 2025-11-22 +**Status:** Identificação Completa +**Prioridade:** CRÍTICA + +Este documento lista todos os arquivos "stub" (redirecionamento) encontrados na documentação do Ansible que devem ser removidos como parte do plano de melhorias. + +--- + +## 📊 Sumário + +- **Total de arquivos stub identificados:** 54 +- **Diretório principal afetado:** `/docs/docsite/rst/user_guide/` +- **Tamanho médio:** 5-6 linhas +- **Impacto:** Alto - Experiência do usuário degradada + +--- + +## 🗂️ Lista Completa de Arquivos Stub + +### Categoria: Conceitos Básicos (4 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/basic_concepts.rst` | 7 | `:ref:\`Getting started with Ansible\`` | +| `user_guide/intro.rst` | 15 | Múltiplos (índice vazio) | +| `user_guide/intro_patterns.rst` | 5 | `:ref:\`intro_patterns\`` | +| `user_guide/cheatsheet.rst` | 6 | `:ref:\`cheatsheet\`` | + +--- + +### Categoria: Inventário (3 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/intro_inventory.rst` | 6 | `:ref:\`intro_inventory\`` | +| `user_guide/intro_dynamic_inventory.rst` | 6 | `:ref:\`intro_dynamic_inventory\`` | +| `user_guide/intro_adhoc.rst` | 6 | `:ref:\`intro_adhoc\`` | + +--- + +### Categoria: Comandos e Conexões (3 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/command_line_tools.rst` | 6 | `:ref:\`command_line_tools\`` | +| `user_guide/connection_details.rst` | 6 | `:ref:\`connections\`` | +| `user_guide/become.rst` | 6 | `:ref:\`playbooks_privilege_escalation\`` | + +--- + +### Categoria: Playbooks - Básico (8 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/playbooks.rst` | 5 | `:ref:\`working_with_playbooks\`` | +| `user_guide/playbooks_intro.rst` | 6 | `:ref:\`playbooks_intro\`` | +| `user_guide/playbooks_best_practices.rst` | 6 | `:ref:\`tips_and_tricks\`` | +| `user_guide/playbooks_reuse.rst` | 6 | `:ref:\`playbooks_reuse\`` | +| `user_guide/playbooks_reuse_includes.rst` | 6 | `:ref:\`playbooks_reuse\`` | +| `user_guide/playbooks_reuse_roles.rst` | 7 | `:ref:\`playbooks_reuse_roles\`` | +| `user_guide/playbooks_advanced_syntax.rst` | 6 | `:ref:\`playbooks_advanced_syntax\`` | +| `user_guide/sample_setup.rst` | 6 | `:ref:\`sample_setup\`` | + +--- + +### Categoria: Playbooks - Controle de Fluxo (8 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/playbooks_conditionals.rst` | 6 | `:ref:\`playbooks_conditionals\`` | +| `user_guide/playbooks_loops.rst` | 6 | `:ref:\`playbooks_loops\`` | +| `user_guide/playbooks_blocks.rst` | 6 | `:ref:\`playbooks_blocks\`` | +| `user_guide/playbooks_handlers.rst` | 5 | `:ref:\`handlers\`` | +| `user_guide/playbooks_tags.rst` | 6 | `:ref:\`tags\`` | +| `user_guide/playbooks_delegation.rst` | 5 | `:ref:\`playbooks_delegation\`` | +| `user_guide/playbooks_async.rst` | 5 | `:ref:\`playbooks_async\`` | +| `user_guide/playbooks_strategies.rst` | 5 | `:ref:\`playbooks_strategies\`` | + +--- + +### Categoria: Playbooks - Variáveis e Dados (6 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/playbooks_variables.rst` | 6 | `:ref:\`playbooks_variables\`` | +| `user_guide/playbooks_vars_facts.rst` | 6 | `:ref:\`vars_and_facts\`` | +| `user_guide/playbooks_prompts.rst` | 6 | `:ref:\`playbooks_prompts\`` | +| `user_guide/playbooks_filters.rst` | 6 | `:ref:\`playbooks_filters\`` | +| `user_guide/playbooks_filters_ipaddr.rst` | 8 | `:ref:\`plugins_in_ansible.utils\`` | +| `user_guide/complex_data_manipulation.rst` | 5 | `:ref:\`complex_data_manipulation\`` | + +--- + +### Categoria: Playbooks - Testes e Lookups (3 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/playbooks_tests.rst` | 6 | `:ref:\`playbooks_tests\`` | +| `user_guide/playbooks_lookups.rst` | 6 | `:ref:\`playbooks_lookups\`` | +| `user_guide/playbooks_module_defaults.rst` | 5 | `:ref:\`module_defaults\`` | + +--- + +### Categoria: Playbooks - Debugging e Execução (4 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/playbooks_debugger.rst` | 6 | `:ref:\`playbook_debugger\`` | +| `user_guide/playbooks_error_handling.rst` | 6 | `:ref:\`playbooks_error_handling\`` | +| `user_guide/playbooks_checkmode.rst` | 6 | `:ref:\`check_mode_dry\`` | +| `user_guide/playbooks_startnstep.rst` | 6 | `:ref:\`playbooks_start_and_step\`` | + +--- + +### Categoria: Playbooks - Ambiente (1 arquivo) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/playbooks_environment.rst` | 5 | `:ref:\`playbooks_environment\`` | + +--- + +### Categoria: Módulos e Plugins (4 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/modules.rst` | 5 | `:ref:\`modules_plugins_index\`` | +| `user_guide/modules_intro.rst` | 5 | `:ref:\`modules_plugins_index\`` | +| `user_guide/modules_support.rst` | 6 | `:ref:\`modules_plugins_index\`` | +| `user_guide/plugin_filtering_config.rst` | 6 | `:ref:\`modules_plugins_index\`` | + +--- + +### Categoria: Collections (1 arquivo) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/collections_using.rst` | 7 | `:ref:\`collections_index\`` | + +--- + +### Categoria: Vault (1 arquivo) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/vault.rst` | 6 | `:ref:\`vault_guide_index\`` | + +--- + +### Categoria: Windows (8 arquivos) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/intro_windows.rst` | 4 | `:ref:\`os_guide_index\`` | +| `user_guide/windows.rst` | 6 | `:ref:\`os_guide_index\`` | +| `user_guide/windows_setup.rst` | 5 | `:ref:\`working_with_windows\`` | +| `user_guide/windows_usage.rst` | 5 | `:ref:\`windows_usage\`` | +| `user_guide/windows_winrm.rst` | 5 | `:ref:\`windows_winrm\`` | +| `user_guide/windows_faq.rst` | 5 | `:ref:\`working_with_windows\`` | +| `user_guide/windows_dsc.rst` | 5 | `:ref:\`windows_dsc\`` | +| `user_guide/windows_performance.rst` | 5 | `:ref:\`windows_performance\`` | + +--- + +### Categoria: BSD (1 arquivo) + +| Arquivo | Linhas | Redireciona Para | +|---------|--------|------------------| +| `user_guide/intro_bsd.rst` | 5 | `:ref:\`working_with_bsd\`` | + +--- + +## 📋 Análise por Categoria + +### Distribuição de Stubs + +``` +Playbooks (Controle/Vars/Testes/Debug): 21 arquivos (39%) +Windows: 8 arquivos (15%) +Conceitos Básicos: 4 arquivos (7%) +Módulos/Plugins: 4 arquivos (7%) +Inventário: 3 arquivos (6%) +Comandos/Conexões: 3 arquivos (6%) +Outras: 11 arquivos (20%) +``` + +### Tamanho dos Arquivos + +``` +4 linhas: 1 arquivo +5 linhas: 19 arquivos (35%) +6 linhas: 31 arquivos (57%) +7 linhas: 2 arquivos +8 linhas: 1 arquivo +15 linhas: 1 arquivo (intro.rst - caso especial) +``` + +--- + +## 🔍 Padrões Identificados + +### Padrão 1: Redirecionamento Simples +**Estrutura típica:** +```rst +:orphan: + +************* +Título do Documento +************* + +This page has moved to :ref:`new_location`. +``` + +**Quantidade:** 52 arquivos +**Nota:** Todos usam `:orphan:` directive (não aparece em toctree) + +--- + +### Padrão 2: Redirecionamento com Contexto +**Estrutura:** +```rst +:orphan: + +Título +====== + +You can find documentation for [topic] at :ref:`new_location`. +``` + +**Quantidade:** 2 arquivos (Windows) +**Exemplos:** `intro_windows.rst`, `windows.rst` + +--- + +## 🎯 Plano de Remoção + +### Fase 1: Preparação (Semana 1) + +**Tarefas:** +1. [x] Identificar todos os arquivos stub +2. [ ] Auditar links que apontam para stubs +3. [ ] Criar mapeamento completo (old → new) +4. [ ] Identificar links externos conhecidos + +**Comando para encontrar referências:** +```bash +# Para cada stub, encontrar referências +grep -r "user_guide/playbooks.rst" docs/docsite/rst/ + +# Ou buscar por referências do tipo :doc: +grep -r ":doc:\`.*user_guide/" docs/docsite/rst/ +``` + +--- + +### Fase 2: Atualização de Links (Semana 1-2) + +**Tarefas:** +1. [ ] Atualizar links internos na documentação +2. [ ] Atualizar links em `index.rst` files +3. [ ] Atualizar links em toctrees +4. [ ] Verificar links em comentários/exemplos + +**Script auxiliar:** +```bash +# Substituir referências +find docs/docsite/rst -name "*.rst" -exec sed -i 's/:doc:`user_guide\/playbooks`/:doc:`playbook_guide\/playbooks_intro`/g' {} \; +``` + +--- + +### Fase 3: Configurar Redirecionamentos (Semana 2) + +**Local:** `docs/docsite/rst/conf.py` + +**Adicionar ao conf.py:** +```python +# HTTP 301 redirects para arquivos movidos +html_additional_pages = {} + +# Ou usar extensão sphinx-reredirects +extensions.append('sphinx_reredirects') + +redirects = { + "user_guide/playbooks": "../playbook_guide/playbooks_intro.html", + "user_guide/modules": "../module_plugin_guide/modules_plugins_index.html", + # ... (adicionar todos os 54) +} +``` + +**Alternativa - Arquivo htaccess:** +```apache +# .htaccess ou configuração nginx +Redirect 301 /user_guide/playbooks.html /playbook_guide/playbooks_intro.html +``` + +--- + +### Fase 4: Validação (Semana 2) + +**Tarefas:** +1. [ ] Build completo da documentação +2. [ ] Verificar zero broken links +3. [ ] Testar redirecionamentos +4. [ ] Verificar search index +5. [ ] Testar navegação + +**Comandos de validação:** +```bash +# Build com linkcheck +nox -s "checkers(docs-build)" + +# Ou +sphinx-build -b linkcheck docs/docsite/rst/ build/linkcheck/ + +# Verificar warnings +sphinx-build -W -b html docs/docsite/rst/ build/html/ +``` + +--- + +### Fase 5: Remoção (Semana 3) + +**Tarefas:** +1. [ ] Backup de arquivos (git já faz isso) +2. [ ] Deletar todos os 54 arquivos stub +3. [ ] Atualizar `.gitignore` se necessário +4. [ ] Commit com mensagem clara + +**Comando de remoção:** +```bash +# Remover todos os stubs (CUIDADO!) +# Executar apenas após validação completa + +cd docs/docsite/rst/user_guide/ +rm -f basic_concepts.rst intro.rst intro_patterns.rst cheatsheet.rst \ + intro_inventory.rst intro_dynamic_inventory.rst intro_adhoc.rst \ + command_line_tools.rst connection_details.rst become.rst \ + playbooks.rst playbooks_*.rst \ + modules.rst modules_*.rst plugin_filtering_config.rst \ + collections_using.rst vault.rst \ + intro_windows.rst windows*.rst intro_bsd.rst \ + complex_data_manipulation.rst sample_setup.rst + +# Verificar o que foi removido +git status +``` + +--- + +### Fase 6: Comunicação (Semana 3) + +**Tarefas:** +1. [ ] Criar blog post sobre mudanças +2. [ ] Comunicar em mailing list +3. [ ] Atualizar changelog +4. [ ] Adicionar nota em release notes + +**Template de comunicação:** +```markdown +# Documentation Structure Cleanup + +As part of ongoing improvements, we've removed redirect-only stub files +from the user_guide/ directory. All content has been migrated to the new +structure (playbook_guide/, inventory_guide/, etc.). + +If you have bookmarked links, they will automatically redirect to the +new locations. External documentation may need to be updated. + +Old structure: /user_guide/playbooks.rst +New structure: /playbook_guide/playbooks_intro.rst + +Full mapping: [link to DOCUMENTATION_GUIDE.md] +``` + +--- + +## 🚨 Riscos e Mitigações + +### Risco 1: Links Externos Quebrados +**Probabilidade:** Alta +**Impacto:** Médio +**Mitigação:** +- Implementar HTTP 301 redirects permanentes +- Manter por pelo menos 2 major releases (1+ ano) +- Comunicar mudanças amplamente + +--- + +### Risco 2: Search Engine Indexing +**Probabilidade:** Média +**Impacto:** Médio +**Mitigação:** +- Usar 301 redirects (preserva SEO) +- Submeter sitemap atualizado ao Google +- Aguardar reindexação natural + +--- + +### Risco 3: Documentação de Terceiros +**Probabilidade:** Alta +**Impacto:** Baixo +**Mitigação:** +- Redirects automáticos resolvem +- Comunidade pode abrir PRs em repos conhecidos +- Adicionar aviso em release notes + +--- + +### Risco 4: Usuários com Docs Offline +**Probabilidade:** Baixa +**Impacto:** Baixo +**Mitigação:** +- Incluir mapeamento em README +- Adicionar ao changelog +- Versão antiga ainda disponível em tags + +--- + +## ✅ Checklist de Validação + +**Antes da Remoção:** +- [ ] Todos os links internos atualizados +- [ ] Redirecionamentos configurados +- [ ] Build completo sem erros +- [ ] Zero broken links +- [ ] Mapeamento documentado +- [ ] Equipe informada + +**Após a Remoção:** +- [ ] Build completo sem erros +- [ ] Redirecionamentos funcionando +- [ ] Navegação testada +- [ ] Search funcionando +- [ ] Comunicação enviada +- [ ] PR revisado e aprovado + +--- + +## 📊 Métricas de Sucesso + +### Antes da Limpeza +- Arquivos stub: 54 +- Redirecionamentos: 0 +- Estrutura: Duplicada (old + new) +- Confusão de usuários: Alta + +### Após a Limpeza +- Arquivos stub: 0 +- Redirecionamentos: 54 (automáticos) +- Estrutura: Única e clara +- Confusão de usuários: Baixa + +### KPIs a Monitorar +- Broken links: deve ser 0 +- User satisfaction: +20% +- Time to find info: -30% +- Documentation issues: -40% + +--- + +## 🔗 Recursos Relacionados + +- [Análise Detalhada](DOCUMENTATION_ANALYSIS.md) +- [Guia de Navegação](DOCUMENTATION_GUIDE.md) +- [Roadmap de Melhorias](IMPROVEMENT_ROADMAP.md) +- [Sphinx Redirects Extension](https://github.com/wpilibsuite/sphinxext-rediraffe) + +--- + +## 📝 Comandos Úteis + +### Análise de Stubs +```bash +# Listar todos os arquivos pequenos +find docs/docsite/rst/user_guide -name "*.rst" -size -500c + +# Contar linhas de cada arquivo +find docs/docsite/rst/user_guide -name "*.rst" -exec wc -l {} \; | sort -n + +# Ver conteúdo de arquivos pequenos +for f in docs/docsite/rst/user_guide/*.rst; do + [ $(wc -l < "$f") -lt 10 ] && echo "=== $f ===" && cat "$f" && echo "" +done +``` + +### Busca de Referências +```bash +# Procurar referências a user_guide +grep -r "user_guide/" docs/docsite/rst/ --include="*.rst" | wc -l + +# Procurar por tipo de link +grep -r ":doc:\`.*user_guide" docs/docsite/rst/ --include="*.rst" +grep -r ":ref:\`.*user_guide" docs/docsite/rst/ --include="*.rst" +``` + +### Validação +```bash +# Build e verificação de links +nox -s make +nox -s "checkers(docs-build)" + +# Verificar warnings +sphinx-build -W -b html docs/docsite/rst/ build/html/ 2>&1 | grep -i warning +``` + +--- + +## 🎯 Próximos Passos Imediatos + +**Esta Semana:** +1. ✅ Inventário completo criado +2. [ ] Auditar links que apontam para stubs +3. [ ] Começar atualização de links internos +4. [ ] Planejar configuração de redirects + +**Próximas 2 Semanas:** +1. [ ] Completar atualização de links +2. [ ] Configurar redirecionamentos +3. [ ] Validar build completo +4. [ ] Remover stubs + +**Próximo Mês:** +1. [ ] Monitorar redirecionamentos +2. [ ] Coletar feedback +3. [ ] Ajustar se necessário + +--- + +**Documento mantido por:** Equipe de Documentação Ansible +**Última atualização:** 2025-11-22 +**Status:** Identificação Completa - Pronto para Fase 1