{"id":50455261,"url":"https://github.com/basedosdados/manual-equipe-dados","last_synced_at":"2026-06-01T02:04:12.784Z","repository":{"id":356372029,"uuid":"1231988763","full_name":"basedosdados/manual-equipe-dados","owner":"basedosdados","description":"Repositório de Documentação como Código para centralizar docs e processos da equipe dados","archived":false,"fork":false,"pushed_at":"2026-05-18T19:58:32.000Z","size":100,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T21:59:50.109Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basedosdados.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T13:33:23.000Z","updated_at":"2026-05-07T18:56:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/basedosdados/manual-equipe-dados","commit_stats":null,"previous_names":["basedosdados/manual-equipe-dados"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/basedosdados/manual-equipe-dados","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fmanual-equipe-dados","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fmanual-equipe-dados/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fmanual-equipe-dados/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fmanual-equipe-dados/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basedosdados","download_url":"https://codeload.github.com/basedosdados/manual-equipe-dados/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fmanual-equipe-dados/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33756587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T02:04:09.648Z","updated_at":"2026-06-01T02:04:12.778Z","avatar_url":"https://github.com/basedosdados.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# manual-equipe-dados\n\nDocumentação como código da equipe dados da Base dos Dados. Fonte oficial e centralizada de processos, infraestrutura, padrões de pipeline, observabilidade e governança.\n\n## Onde está o conteúdo\n\nA documentação vive em [`docs/`](docs/index.md). Comece pelo [índice principal](docs/index.md).\n\n## Lógica da estrutura\n\nEste manual é organizado segundo o framework **[Diátaxis](https://diataxis.fr/)**, criado por Daniele Procida. A premissa do Diátaxis é que toda documentação técnica atende a quatro necessidades distintas, e misturá-las num mesmo documento é a principal causa de docs difíceis de ler:\n\n| Modo | Pergunta do leitor | Orientação |\n|---|---|---|\n| **Tutorial** | \"Como começo?\" | Aprendizado guiado, do zero |\n| **Como-fazer** | \"Como faço X?\" | Tarefa específica, leitor já sabe o que precisa |\n| **Referência** | \"O que é Y?\" | Consulta factual de valores, schemas, definições |\n| **Explicação** | \"Por que é assim?\" | Conceitos, decisões, contexto histórico |\n\nA estes quatro modos canônicos, o manual adiciona dois subtipos pragmáticos:\n\n- **Runbook** — subtipo de how-to voltado a resolução de incidentes operacionais. Lido sob pressão, indexado pelo *sintoma*.\n- **ADR** (Architecture Decision Record) — subtipo de explicação que registra decisões arquiteturais com contexto, alternativas consideradas e consequências.\n\n### Por que domínio no topo, e não modo\n\nA [documentação oficial do Diátaxis sobre hierarquias complexas](https://diataxis.fr/complex-hierarchies/) recomenda que, em projetos com múltiplos domínios, a estrutura de pastas seja organizada **primeiro por assunto** e só depois pelo modo Diátaxis. A razão: quem chega na doc não pensa \"preciso de uma referência\", pensa \"preciso entender custos da GCP\". Forçar o leitor a saber em qual modo sua dúvida cai sobrecarrega a navegação.\n\nPor isso a estrutura deste repositório é:\n\n```\ndocs/\n  \u003cdominio\u003e/              # processos, infraestrutura, pipelines, ...\n    index.md              # mapa do domínio\n    explicacao/           # \"por quê?\"\n    como-fazer/           # \"como faço X?\"\n    referencia/           # \"o que é Y?\"\n    runbooks/             # \"quebrou, e agora?\"\n    adr/                  # decisões arquiteturais\n```\n\nSub-pastas Diátaxis só existem nos domínios em que o volume justifica. Em domínios menores, os arquivos ficam soltos com prefixo no nome (`como-X.md`, `referencia-Y.md`, `explicacao-Z.md`).\n\n### Convenções derivadas\n\n- **`index.md` em toda pasta** — funciona como mapa do domínio, não como README genérico.\n- **Frontmatter obrigatório** com `tipo:` em todo arquivo, permitindo linting e índices automáticos por modo.\n- **Uma página por unidade atômica** — uma métrica, uma decisão, um runbook. Não agrupar.\n- **Tutoriais só em `onboarding/`** — nos demais domínios eles raramente fazem sentido.\n\n## Como contribuir\n\nAntes de criar ou editar uma página, leia [CONTRIBUTING.md](CONTRIBUTING.md). Ele traz a tabela \"se o leitor vai… → modo → template\" para escolher o modo certo, além das convenções de naming e do fluxo de PR.\n\n## Renderizar o site localmente\n\nDependências são gerenciadas com [uv](https://docs.astral.sh/uv/). Instale-o uma vez:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nPara servir a documentação localmente:\n\n```bash\nuv sync\nuv run mkdocs serve\n```\n\nSite servido em \u003chttp://127.0.0.1:8000\u003e.\n\nPara adicionar uma nova dependência (ex: um plugin do MkDocs):\n\n```bash\nuv add \u003cpacote\u003e\n```\n\nSempre commite o `uv.lock` junto com o `pyproject.toml`.\n\n## Referências\n\n- [Diátaxis — site oficial](https://diataxis.fr/)\n- [The Documentation System (Daniele Procida)](https://documentation.divio.com/) — versão anterior do mesmo framework, ainda boa leitura\n- [Architecture Decision Records (Michael Nygard)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) — formato base dos ADRs deste manual","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedosdados%2Fmanual-equipe-dados","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasedosdados%2Fmanual-equipe-dados","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedosdados%2Fmanual-equipe-dados/lists"}