Guia de Padrões do OLQA (M2/M3)

Sempre que você for criar ou revisar uma página, trilha, grafo, componente ou dataset do OLQA, passe rapidamente por este guia. A ideia não é burocratizar, mas evitar decisões aleatórias que, no futuro, dificultem automatização e evolução do livro.

Uma rotina mínima recomendada:

1. Verifique a terminologia (seção 1) – evite sinônimos improvisados para conceitos centrais.
2. Confirme o padrão de nomeação de arquivos e páginas (seção 2) antes de salvar novas versões.
3. Siga o padrão de página OLQA (cabeçalho fixo, breadcrumb, cards) ao estruturar novos artefatos (seção 3).
4. Se usar grafos, aplique os padrões D3.js (cores, grupos, predicados, interações) (seção 4).
5. Ajuste a interatividade (scroll suave, acordeões, modais, filtros) seguindo a seção 5.
6. Revise o texto com base nos padrões editoriais (seção 6) e garanta o bloco “Nível de Abstração M0–M3” quando fizer sentido.

O OLQA é um sistema intensivo em conceitos. Pequenas variações de linguagem podem quebrar relações futuras em grafos, glossários e mecanismos de pesquisa. Por isso, alguns termos têm forma oficial.

Convenções básicas:

• Nome do sistema: “OLQA · O Livro que Aprende” (em títulos), “OLQA” em trechos internos.
• Camadas: “M0”, “M1”, “M2”, “M3” (sempre em maiúsculo, sem hífen nas siglas; com hífen apenas em descrições como “Camadas M0–M3”).
• Grafo: use “grafo interativo” ou “visualização”, evitando misturar com “mapa” quando já existe “Mapa do Ecossistema”.
• Aprendiz vs. “usuário”: prefira “aprendiz” para o papel principal; “usuário” apenas em contextos técnicos (sistema, autenticação, logs).
• Livro 5.0: conceito central, sempre com “5.0” explicitado quando falar da geração do livro.

A lógica de arquivos e versões é parte da “memória externa” do OLQA. A consistência aqui facilita migrações futuras, automação de deploy e leitura histórica do projeto.

• Páginas estáveis por função:
  • index.html – landing page pública atual.
  • indexatual.html – home do conteúdo principal atual.
  • RedeTopicos.html – grafo interativo em produção.
  • modelo_conceitual_olqa.html – catálogo de modelos M2/M3.
  • padroes_OLQA.html – este guia.
• Versões de linha do tempo:
  • index23v1.html, index24v8.html, index26v8.html.
  • v indica versão dentro do ano, não patch técnico.
• Convenção de nome de arquivos de modelo:
  • Use nomes descritivos em português, com camelCase leve ou underscore.
  • Ex.: camadas_M0_M3_Livro5.html, meta_modelo_AEIOU.html.
• Diretórios principais (exemplos):
  • WDLab/ – laboratório de páginas e protótipos.
  • WDGestao/ – páginas de gestão, histórico, linha do tempo.
  • Outros diretórios temáticos seguem esse padrão “WD + tema”.

As páginas do OLQA compartilham um “esqueleto” visual. Isso permite que o aprendiz sinta consistência, mesmo mudando de domínio ou nível.

Elementos obrigatórios em páginas OLQA de M1/M2/M3:

• Cabeçalho fixo com logo “OLQA · O Livro que Aprende” e menu horizontal principal.
• Breadcrumb logo abaixo do cabeçalho, indicando posição na arquitetura.
• Seção hero com título claro, subtítulo e, se fizer sentido, um par de botões de ação (ex.: “Ver grafo”, “Como usar esta página”).
• Cards para blocos de conteúdo principais, com visual consistente (bordas suaves, gradiente discreto, texto legível).
• Rodapé com assinatura e informação de camada (“Camada de Modelos Conceituais (M2/M3)”, por exemplo).

Os grafos são peças centrais do OLQA. Eles precisam ser legíveis, previsíveis e coerentes entre páginas. Alguns padrões mínimos:

• Grupos e cores:
  • Grupo 1 – Níveis / camadas (ex.: Ensino, M0–M3).
  • Grupo 2 – Usos / cenários.
  • Grupo 3 – Personas.
  • Grupo 4 – Componentes / artefatos.
  • Grupo 5 – Entidades de negócio, etc.
• Predicados nas setas: nomeie as relações (ex.: “usa”, “depende de”, “alimenta”, “refina”).
• Interação mínima: arrastar nós, zoom e pan no grafo inteiro, tooltip ao passar o mouse/toque e tema claro/escuro com contraste adequado.
• Forças e estabilidade: evitar “explosão” do grafo, usando forças moderadas e limites de deslocamento (mantendo a legibilidade).

A interatividade deve apoiar a compreensão, não competir com o conteúdo. Alguns elementos recorrentes têm comportamento padrão:

• Scroll suave para links internos com id (botões “Como usar esta página”, “Ver grafo”).
• Acordeões para narrativas mais densas (ex.: “Como ler esta página”, modo Iniciante / Intermediário / Avançado).
• Modais para fichas de persona, glossário detalhado, explicações locais (sempre com botão de fechar visível).
• Filtros para grafos (por grupo, por camada M0–M3, por papel – aprendiz/autor/engenheiro).
• Botão “voltar ao topo” em páginas longas, flutuando no canto inferior direito.

A escrita no OLQA busca clareza, contexto e ligação com as camadas M0–M3. Ela alterna entre narrativa leve e trechos técnicos mais densos, sempre sinalizados.

• Títulos focados na função da página (ex.: “Rede de Tópicos do OLQA (M2/M3)”, “Trilha de Aprendizagem X”).
• Subtítulos explicam em 1–2 frases “para que serve” aquele artefato.
• Blocos monoespaçados (monobox) marcam trechos normativos, exemplos de pseudo-código de processo, listas de checklist e resumos de camadas M0–M3.
• Uso de listas (ul/ol) para quebrar raciocínios e apoiar leitura por partes.
• Ligações entre camadas: deixar explícito onde a página se posiciona (M0/M1/M2/M3) e como ela conversa com outras páginas.

Muitos objetos de aprendizagem do OLQA seguem a abordagem “começar pelo problema resolvido”. Esse padrão também precisa ser consistente.

• A página traz logo no início um quadro simples com o problema já resolvido (ex.: a balança, o grafo final, o diagrama de estado, a página mockada).
• Em seguida, vem uma seção “Como chegamos aqui?” ou equivalente, quebrando a solução em etapas.
• Sempre que possível, conecte o problema resolvido a um uso real do OLQA (caso, jornada, cenário).

O OLQA trabalha com múltiplas camadas de abstração. Padrões de contexto e navegação ajudam o leitor a não “se perder” entre M0, M1, M2 e M3.

• Breadcrumbs devem refletir a posição da página dentro da arquitetura (ex.: Home → Modelos Conceituais → Guia de Padrões).
• Bloco explicando M0–M3 deve aparecer pelo menos uma vez nas páginas que tratam diretamente de camadas.
• Mini-mapas visuais (diagramas simples) podem mostrar onde a página se encontra na arquitetura geral do OLQA.
• Links cruzados:
  • De M2/M3 (conceitual) → para M0/M1 (operacional) sempre que houver versão prática.
  • De M0/M1 → de volta para a página conceitual, quando o aprendiz quiser “ver os bastidores”.