78 lines
2.4 KiB
Markdown
78 lines
2.4 KiB
Markdown
# 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.
|