adjustments on docs
This commit is contained in:
@@ -1,81 +0,0 @@
|
||||
# Agenda - Single Canonical Architecture
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje a arquitetura do runtime está fragmentada em documentos com níveis diferentes de autoridade.
|
||||
|
||||
Na prática existem pelo menos dois problemas:
|
||||
|
||||
- mais de um documento tenta falar pela arquitetura;
|
||||
- um deles ainda se apresenta como `stub`, enquanto outro se declara baseline canônico.
|
||||
|
||||
## Dor
|
||||
|
||||
- Contribuidores perdem tempo tentando descobrir qual documento manda.
|
||||
- PR arquitetural pode ser validada por um texto e contrariar outro.
|
||||
- A documentação deixa de servir como guardrail e passa a gerar ambiguidade.
|
||||
- O projeto perde disciplina exatamente na camada que deveria fixar invariantes.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir um único documento canônico de arquitetura do runtime, com papel explícito para cada outro documento remanescente.
|
||||
|
||||
O alvo é matar a ambiguidade, não só mover arquivos.
|
||||
|
||||
Ao final da discussão deve ficar claro:
|
||||
|
||||
- qual documento é canônico;
|
||||
- quais docs são derivativos, históricos ou de apoio;
|
||||
- o que deve ser removido, fundido ou rebaixado de autoridade.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Documento canônico.
|
||||
Onde vive a arquitetura mandatória do runtime.
|
||||
|
||||
2. Escopo do documento.
|
||||
Quais invariantes ele deve cobrir:
|
||||
- execution model
|
||||
- memory model
|
||||
- safepoints
|
||||
- scheduler
|
||||
- verifier
|
||||
- syscall ABI
|
||||
- firmware/runtime boundary
|
||||
|
||||
3. Papel dos demais docs.
|
||||
O que é:
|
||||
- arquitetura normativa
|
||||
- roadmap
|
||||
- histórico
|
||||
- specification detalhada
|
||||
- material pedagógico
|
||||
|
||||
4. Política de atualização.
|
||||
Mudança arquitetural deve exigir atualização do doc canônico no mesmo PR?
|
||||
|
||||
5. Estratégia de remoção do `stub`.
|
||||
Se será apagado, redirecionado ou transformado em índice.
|
||||
|
||||
## O Que Necessita Para Resolver
|
||||
|
||||
- inventário dos docs que hoje competem por autoridade;
|
||||
- decisão de taxonomia documental;
|
||||
- definição do local canônico;
|
||||
- plano de migração de conteúdo sem perder contexto útil;
|
||||
- regra de governança para futuras PRs arquiteturais.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- reorganização completa de todo o diretório `docs/`;
|
||||
- rewrite estilístico de todo material pedagógico;
|
||||
- padronização editorial fina além do necessário para eliminar ambiguidade.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver:
|
||||
|
||||
- definição do documento canônico;
|
||||
- lista do que será removido, fundido ou rebaixado;
|
||||
- regra explícita de atualização futura;
|
||||
- plano curto de migração sem deixar lacuna documental.
|
||||
@@ -1,77 +0,0 @@
|
||||
# Agenda - Hardware Specs Reorganization
|
||||
|
||||
## Problema
|
||||
|
||||
As specs de hardware hoje estão com cara de colcha de retalhos.
|
||||
|
||||
Há material útil, mas a organização mistura:
|
||||
|
||||
- capítulos extensos e narrativos;
|
||||
- conteúdo normativo e conteúdo pedagógico;
|
||||
- temas de VM, firmware, cartridge, assets e ABI no mesmo bloco de "hardware";
|
||||
- granularidade desigual entre capítulos.
|
||||
|
||||
## Dor
|
||||
|
||||
- Fica difícil saber o que é norma e o que é explicação.
|
||||
- A navegação está ruim para quem precisa alterar um domínio específico.
|
||||
- Ownership documental por área não está claro.
|
||||
- Revisões futuras tendem a acrescentar mais remendos em vez de consolidar o modelo.
|
||||
- O risco de contradição entre spec, arquitetura e implementação cresce.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir uma organização coerente para as specs do sistema, com separação clara entre:
|
||||
|
||||
- spec normativa;
|
||||
- material conceitual/pedagógico;
|
||||
- arquitetura de runtime;
|
||||
- domínios de hardware/periféricos;
|
||||
- firmware, cartridge e tooling-related specs.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Taxonomia das specs.
|
||||
Quais grandes categorias devem existir:
|
||||
- machine/runtime
|
||||
- hardware/peripherals
|
||||
- firmware/system
|
||||
- cartridge/package
|
||||
- host ABI
|
||||
- assets/tooling
|
||||
|
||||
2. Critério de corte.
|
||||
O que pertence a "hardware" de fato e o que deve sair desse pacote.
|
||||
|
||||
3. Estrutura de navegação.
|
||||
Como organizar índice, capítulos, subpastas e documentos canônicos por domínio.
|
||||
|
||||
4. Nível de autoridade.
|
||||
Quais documentos são normativos e quais são apenas explicativos.
|
||||
|
||||
5. Estratégia de migração.
|
||||
Como reorganizar sem quebrar referências, sem perder contexto e sem reescrever tudo de uma vez.
|
||||
|
||||
## O Que Necessita Para Resolver
|
||||
|
||||
- inventário da estrutura atual;
|
||||
- proposta de taxonomia e árvore de diretórios;
|
||||
- mapeamento capítulo atual -> destino futuro;
|
||||
- política para docs históricos ou híbridos;
|
||||
- critério mínimo de consistência editorial para novos documentos.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- reescrever toda a spec de hardware imediatamente;
|
||||
- normalizar cada frase ou estilo de escrita;
|
||||
- atualizar todo conteúdo técnico de cada capítulo nesta mesma discussão.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver:
|
||||
|
||||
- taxonomia alvo aprovada;
|
||||
- nova árvore de organização definida;
|
||||
- mapa de migração dos capítulos atuais;
|
||||
- decisão sobre normativo vs pedagógico;
|
||||
- plano incremental de execução.
|
||||
Reference in New Issue
Block a user