Critérios de Qualidade das Notas

Nota 10 do capítulo 27 - Governança da Biblioteca de CTI. Define os critérios que governam a forma e o conteúdo de todas as notas da biblioteca e o processo que os aplica.
Cobre o catálogo de critérios de formato e de conteúdo, o checklist de revisão em bloco de código, o fluxo de revisão por pares e o template de issue de revisão, fechando com a tabela de critérios e formas de verificação.
Dialoga com os templates da nota 07 e com o versionamento da nota 11, e é a referência obrigatória para qualquer autor que crie ou corrija notas nos capítulos 01 a 26.

1. Contexto e Posicionamento na Biblioteca

Uma biblioteca de estudos vale o que vale sua confiabilidade, e confiabilidade em acervo de conhecimento tem dois componentes: precisão técnica do que está escrito e previsibilidade de forma, que permite ao leitor encontrar qualquer informação no lugar esperado. A precisão técnica é conquistada nas notas dos capítulos temáticos e no ciclo de revisão; a previsibilidade de forma é o que esta nota institui, com um catálogo fechado de critérios que toda nota, sem exceção, precisa cumprir antes de entrar no acervo ou permanecer nele.

Os critérios não são estética. Cada um tem justificativa operacional direta: a faixa de linhas garante notas legíveis em uma sessão de estudo e profundidade suficiente para serem úteis; o H1 sem prefixo permite renomear pastas sem quebrar links internos; o blockquote inicial dá ao leitor o mapa da nota antes do primeiro parágrafo; as seções H2 numeradas sustentam referências cruzadas estáveis entre capítulos; e as proibições de símbolos e de seções fecham as portas para o ruído visual e para o texto que não entrega informação nova. O processo de revisão por pares transforma o catálogo em prática, e o versionamento da nota 11 registra cada mudança de critério no tempo.

2. Catálogo de Critérios de Qualidade

O catálogo usa códigos estáveis, de C-01 a C-14, que o checklist, a issue e a tabela de verificação citam para evitar ambiguidade em discussão de revisão. Os critérios de formato vêm primeiro, porque são verificáveis de forma quase mecânica, e os de conteúdo vêm depois, porque exigem leitura.

Os critérios C-01 a C-04 e C-09 a C-11 são duros, e nota que os viole volta da revisão mesmo com conteúdo excelente, porque quebram a interface comum de leitura. Os critérios C-05 a C-08 e C-12 admitem julgamento de revisor, e a issue de revisão serve exatamente para registrar esse julgamento com argumento técnico e sugestão concreta, e não com preferência estilística pessoal.

3. Checklist de Revisão de Nota

O checklist abaixo é a ferramenta de trabalho do revisor e da auto-revisão do autor, e deve ser percorrido na ordem, antes de qualquer issue ser aberta. O autor faz a primeira passada ao finalizar a nota, e o revisor repete a passada de forma independente, o que converte o checklist em verificação dupla e não em ritual de um só.

CHECKLIST DE REVISAO DE NOTA - Biblioteca CTI-TH
Nota revisada: <capítulo> / <nome do arquivo>
Revisor e data: <nome> / <AAAA-MM-DD>

FORMATO
[ ] C-01 wc -l entre 130 e 230 linhas (alvo 150 a 210)
[ ] C-02 H1 igual ao nome do arquivo, sem prefixo e sem extensão
[ ] C-03 Blockquote de 2 a 4 linhas logo após o H1
[ ] C-04 Seções H2 numeradas do geral para o específico

CONTEUDO
[ ] C-05 Parágrafos com 3 ou mais frases, sem frase isolada
[ ] C-06 Itens de lista explicativos e completos
[ ] C-07 Pelo menos um exemplo prático em bloco de código
[ ] C-08 Tabelas presentes quando agregam valor
[ ] C-12 Última seção substantiva, sem recapitulação vazia

PROIBICOES E IDIOMA
[ ] C-09 Sem travessão, en-dash, seta, emoji ou símbolo decorativo
[ ] C-10 Sem seção de Referências ou Bibliografia
[ ] C-11 Sem seção de Conclusão
[ ] C-13 Acentuação correta e texto em português do Brasil
[ ] C-14 Siglas em inglês, explicadas no primeiro uso

RESULTADO: aprovada | aprovada com ressalvas | devolvida ao autor
Ressalvas registradas em issue: <sim ou não, com número da issue>

A disciplina que faz o checklist funcionar é a do resultado explícito na última linha: aprovada, aprovada com ressalvas ou devolvida, sem área cinza. Ressalva sem issue aberta não existe, porque ressalva não registrada se perde na próxima rotação do time e a nota segue no acervo com defeito conhecido por uma pessoa só.

4. Processo de Revisão por Pares

Toda nota nova e toda edição substantiva de nota existente passa por revisão por pares antes de entrar no acervo, e o processo cabe em cinco passos que o time executa sem cerimônia adicional. Primeiro, o autor finaliza a nota e roda o checklist da seção 3 em auto-revisão, corrigindo o que encontrar. Segundo, o autor abre uma issue de revisão no repositório da biblioteca, com o template da seção 5, e designa um revisor que não seja o autor do texto. Terceiro, o revisor percorre o checklist, testa o que for verificável por comando e registra cada problema com código de critério, localização e sugestão. Quarto, o autor corrige ou responde ponto a ponto até o resultado final, e a issue é fechada com o resultado registrado. Quinto, a nota aprovada entra no acervo ou segue alterada, e a mudança relevante aparece no changelog da nota 11.

A gravidade dos achados usa três níveis que disciplinam o prazo. Bloqueante viola critério duro ou contém erro técnico factual, e a nota não entra no acervo até a correção. Major prejudica a leitura ou a utilidade sem invalidar a nota, com prazo de correção de uma semana. Minor é ajuste local de forma ou de clareza, corrigido no próximo ciclo de manutenção. Esse escalonamento evita o oposto e igualmente nocivo: revisão que trava o acervo por perfeccionismo e revisão que aprova tudo para não criar atrito.

5. Template de Issue de Revisão

A issue de revisão é o registro único do ciclo, e o template abaixo garante que toda issue contenha o mínimo para o autor corrigir sem idas e voltas em chat. O campo de critérios violados usa os códigos da seção 2, e a sugestão de correção é obrigatória, porque apontar defeito sem caminho de solução transfere trabalho em vez de somar.

TITULO: Revisao - Cap XX Nota NN - <titulo da nota>
TIPO: revisão de nota nova | revisão de edição | revisão semestral
CATEGORIA: bloqueante | major | minor

DESCRICAO DO PROBLEMA
<o que está errado, em uma ou mais frases completas>

CRITERIOS VIOLADOS
<códigos do catálogo, como C-01, C-09, separados por vírgula>

LOCALIZACAO
<seção e item, como seção 4, parágrafo 2 ou tabela da seção 6>

SUGESTAO DE CORRECAO
<como corrigir, com texto proposto quando aplicável>

VERIFICACAO FEITA PELO REVISOR
<comandos executados e resultado, como wc -l e busca por símbolos>

REVISOR: <nome>
PRAZO: <AAAA-MM-DD>
RESULTADO FINAL: aprovada | aprovada com ressalvas | devolvida

O campo de verificação executada vale registro à parte, porque documentar o comando usado na verificação transforma cada issue em evidência auditável: qualquer leitor futuro confere que a nota foi revisada com wc -l, com busca de símbolos e com leitura de conteúdo, e não apenas com intenção de boa vontade. Issues fechadas ficam no repositório e servem de histórico para o ciclo semestral da nota 11.

6. Tabela de Critérios e Verificação

A tabela final une o catálogo às formas de verificação, separando o que se confere por comando, o que se confere por inspeção rápida e o que exige leitura atenta, e é a referência que o revisor mantém aberta durante a passada de checklist.

A divisão por tipo tem efeito prático direto no tempo de revisão: cerca de metade dos critérios se resolve em minutos com comando e inspeção, e o esforço do revisor concentra-se na leitura atenta, que é onde o valor de qualidade real aparece. Revisor que começa pela leitura atenta gasta energia em C-01 e C-09 que dois comandos resolvem, e termina sem tempo para o que só humano verifica.

7. Indicadores de Qualidade do Acervo

Os critérios auditam nota a nota, e a governança também precisa de visão agregada, porque um acervo pode estar em conformidade item a item e ainda assim decadente em tendência. Os indicadores abaixo são calculados no ciclo semestral da nota 11, a partir das issues de revisão e das verificações por comando, e dão ao gestor do programa a foto objetiva da saúde do acervo.

Nenhum indicador isolado decide, e a leitura correta é conjunta: conformidade alta com idade de revisão alta significa acervo em ordem formal e conteúdo envelhecendo, que é exatamente o cenário que o ciclo semestral existe para corrigir antes que o leitor perceba.

8. Erros Comuns e Pontos de Atenção

O erro estrutural mais frequente é o critério virar burocracia de carimbo: revisor que marca checklist sem executar as verificações transforma o processo em teatro, e a solução é institucional, com o campo de verificação executada da issue obrigando o registro dos comandos e resultados. O erro oposto, revisão que devolve a nota por preferência pessoal sem código de critério violado, também corrompe o processo, e a regra é simples: achado sem critério violado não é achado de revisão, é conversa, e pertence a outro canal. Entre os dois erros está o caminho do processo saudável, que aplica critério com argumento e prazo.

Atenção ainda à evolução dos critérios: o catálogo desta nota é versionado pela nota 11, e alteração de critério é mudança major da biblioteca, porque afeta todas as notas simultaneamente. Autor que sentir falta de um critério novo abre issue de proposta contra esta nota, a discussão acontece no ciclo de revisão por pares, e o catálogo muda com changelog e com janela de adaptação, nunca no meio de um ciclo de revisão em andamento.

9. Integração com o Restante da Biblioteca

Esta nota é a moldura das demais: as notas dos capítulos 01 a 26 são o objeto que ela audita, os templates da nota 07 são insumo e exemplo vivo dos critérios C-07 e C-08, e o changelog da nota 11 registra tanto a evolução do catálogo quanto o resultado dos ciclos semestrais de revisão que a seção 4 define. O checklist da seção 3 também serve às outras bibliotecas de estudo do mesmo padrão, o que o torna candidato a compartilhamento entre acervos que adotem o mesmo guia de estilo.

Para aplicar esta nota hoje, o caminho é escolher uma nota recente do acervo, rodar o checklist em auto-revisão com os comandos da seção 6 e abrir a primeira issue de revisão real, mesmo que o resultado seja aprovada sem ressalvas. Um ciclo completo de revisão documentado vale mais que qualquer manual sobre o processo, e o repositório de issues passa a partir daí a ser o termômetro objetivo da saúde do acervo.