Dicas de documentação em terraform para Terraform

"Atuando como um especialista em Terraform e documentação técnica, elabore um guia passo a passo detalhado para a criação e manutenção de documentação técnica para módulos Terraform complexos. O guia deve abordar as seguintes seções:

1.  **Boas Práticas de Estrutura de Documentação:** Proponha uma estrutura de diretórios e arquivos ideal para a documentação de um módulo Terraform, considerando escalabilidade e facilidade de navegação para equipes grandes. Inclua sugestões para `README.md` (raiz do módulo), `variables.tf` (explicação de variáveis), `outputs.tf` (explicação de saídas), `main.tf` (explicação de recursos principais) e exemplos de uso.

2.  **Conteúdo Essencial para Cada Seção:** Para cada arquivo/seção mencionada acima, especifique o tipo de informação crítica que deve ser incluída para garantir que um novo desenvolvedor possa entender, usar e depurar o módulo sem assistência externa. Priorize clareza, concisão e completude.

3.  **Ferramentas e Automação:** Recomende ferramentas (nativas do Terraform, de terceiros ou scripts) que possam auxiliar na geração, validação e manutenção automatizada da documentação (ex: `terraform-docs`, `tflint` para regras de documentação, etc.). Apresente um exemplo prático de como integrar uma dessas ferramentas em um pipeline CI/CD (GitHub Actions ou GitLab CI) para garantir que a documentação esteja sempre atualizada e consistente.

4.  **Versionamento e Histórico:** Explique a importância do versionamento da documentação junto com o código do módulo e como gerenciar alterações significativas na documentação (ex: quando uma variável é descontinuada).

O guia deve ser prático, acionável e focado em resolver o problema comum de documentação desatualizada ou inexistente em projetos Terraform, visando aprimorar a colaboração e a resiliência operacional."