Skip to content

ORGANIZATION.md

Latest commit

 

History

History
202 lines (163 loc) · 6.49 KB

ORGANIZATION.md

File metadata and controls

202 lines (163 loc) · 6.49 KB

Organização da Biblioteca — Dev's Café Didática

Este documento define a estrutura hierárquica, nomenclatura de pastas e processo de criação de novos livros.

1. Hierarquia Principal

A biblioteca está organizada em cinco níveis (incluindo língua):

área  →  tecnologia  →  tópico  →  língua  →  item
Nível Descrição Exemplo
Área Domínio de conhecimento amplo matematica, programacao, infraestrutura
Tecnologia Linguagem, ferramenta ou sub-domínio python, javascript, algebra, linux
Tópico Livro ou volume específico (pasta raiz do livro) matematica-para-leigos-vol1
Língua Versão linguística do livro ptpt, ptbr, en
Item Capítulo ou secção dentro do livro 01-numeros-e-operacoes.tex

2. Códigos de Língua

Código Língua
ptpt Português (Portugal)
ptbr Português (Brasil)
en English

Acrescentar novos códigos seguindo o formato ISO 639-1 + região quando necessário.

3. Estrutura de Pastas

livros/
├── <area>/
│   └── <tecnologia>/              (opcional — omitir se área == tecnologia)
│       └── <slug-do-livro>/       (tópico = pasta raiz do livro)
│           ├── <lingua>/          (ptpt, ptbr, en, ...)
│           │   ├── main.tex
│           │   ├── metadata.tex
│           │   ├── preambulo.tex
│           │   ├── bibliografia.bib
│           │   ├── capitulos/
│           │   │   ├── 00-introducao.tex    (item)
│           │   │   ├── 01-<topico>.tex      (item)
│           │   │   └── ...
│           │   ├── assets/
│           │   │   ├── imagens/
│           │   │   └── codigo/
│           │   └── output/
│           └── <outra-lingua>/
│               └── ...

Quando omitir o nível "tecnologia"

Se a área já é suficientemente específica (ex.: matematica), o nível tecnologia pode ser omitido e o livro fica directamente sob a área:

livros/
└── matematica/
    └── matematica-para-leigos-vol1/   ← livro directamente na área

Se a área é ampla (ex.: programacao), o nível tecnologia é obrigatório:

livros/
└── programacao/
    ├── python/
    │   └── python-para-iniciantes-vol1/
    │       ├── ptpt/
    │       └── ptbr/
    └── javascript/
        └── javascript-essencial-vol1/
            └── ptpt/

4. Áreas Definidas

Slug da Área Descrição
matematica Matemática pura e aplicada
programacao Linguagens de programação e paradigmas
infraestrutura Sistemas operativos, redes, cloud
dados Bases de dados, ciência de dados, BI
seguranca Cibersegurança, criptografia
web Desenvolvimento web (front-end e back-end)
fundamentos Ciência da computação, algoritmos, estruturas de dados

Novas áreas podem ser propostas via Pull Request com justificação.

4. Nomenclatura (Regras Obrigatórias)

Pastas e ficheiros

  • kebab-case em minúsculas: matematica-para-leigos-vol1
  • Sem espaços, acentos ou caracteres especiais
  • Números de volume sempre com prefixo vol: vol1, vol2

Slug do livro

Formato: <assunto-principal>-<audiencia-ou-descricao>-vol<N>

Exemplo de título Slug correcto
Matemática para Leigos — Vol. 1 matematica-para-leigos-vol1
Python para Iniciantes — Vol. 2 python-para-iniciantes-vol2
JavaScript Essencial javascript-essencial-vol1
Linux na Prática — Vol. 1 linux-na-pratica-vol1

Capítulos (itens)

  • Numerados com dois dígitos: 00-, 01-, 02-
  • 00-introducao.tex é reservado para a introdução
  • Formato: <NN>-<descricao-kebab>.tex

5. Catálogo (CATALOG.md)

Na raiz do repositório, o ficheiro CATALOG.md (gerado manualmente ou por script) lista todos os livros:

| Área | Livro | Volume | Língua | Status | Caminho |
|---|---|---|---|---|---|
| Matemática | Matemática para Leigos | Vol. 1 | PT-PT | 🚧 Em desenvolvimento | livros/matematica/matematica-para-leigos-vol1/ptpt |
| Matemática | Matemática para Leigos | Vol. 1 | PT-BR | 🚧 Em desenvolvimento | livros/matematica/matematica-para-leigos-vol1/ptbr |

Status permitidos:

  • 🚧 Em desenvolvimento
  • 📝 Em revisão
  • ✅ Publicado
  • 🔒 Arquivado

6. Processo de Criação de Novo Livro

  1. Escolher a área correcta ou propor nova área
  2. Definir o slug seguindo as regras de nomenclatura
  3. Criar a pasta livros/<area>/[tecnologia/]<slug>/
  4. Para cada língua: copiar o template de branding/BOOK-TEMPLATE/ para <slug>/<lingua>/
  5. Preencher metadata.tex com título, autor, versão e data
  6. Criar os ficheiros de capítulo em capitulos/
  7. Registar o livro no CATALOG.md
  8. Submeter Pull Request

7. Exemplo Completo de Árvore

livros/
├── matematica/
│   └── matematica-para-leigos-vol1/
│       ├── ptpt/                        ← Português (Portugal)
│       │   ├── main.tex
│       │   ├── metadata.tex
│       │   ├── preambulo.tex
│       │   ├── bibliografia.bib
│       │   ├── capitulos/
│       │   │   ├── 00-introducao.tex
│       │   │   ├── 01-numeros-e-operacoes.tex
│       │   │   └── ...
│       │   ├── assets/imagens/
│       │   └── output/
│       └── ptbr/                        ← Português (Brasil)
│           ├── main.tex
│           ├── metadata.tex
│           ├── preambulo.tex
│           ├── bibliografia.bib
│           ├── capitulos/
│           │   ├── 00-introducao.tex
│           │   └── ...
│           ├── assets/imagens/
│           └── output/
├── programacao/
│   ├── python/
│   │   └── python-para-iniciantes-vol1/
│   │       ├── ptpt/
│   │       └── ptbr/
│   └── javascript/
│       └── javascript-essencial-vol1/
│           └── ptpt/
├── infraestrutura/
│   └── linux/
│       └── linux-na-pratica-vol1/
│           └── ptpt/
└── dados/
    └── sql/
        └── sql-do-zero-vol1/
            └── ptpt/