Capítulo 5 — Comunicação em engenharia
Mapa da aula
Aula 05 publicada. Mapa, exemplo, EX013.
flowchart TD
N0["5.1 Os documentos do engenheiro"]
N1["5.2 Comunicando incerteza"]
N2["5.3 Documentando componentes de IA"]
N3["5.4 Públicos"]
N4["5.5 Estrutura e rastreabilidade"]
N5["Síntese"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5
N5 --> EX["Exemplo resolvido"]
EX --> Q["Exercício EX013"]
Desenho lógico
flowchart LR
N0["5.1 Os documentos do engenheiro"]
N1["5.2 Comunicando incerteza"]
N2["5.3 Documentando componentes de IA"]
N3["5.4 Públicos"]
N4["5.5 Estrutura e rastreabilidade"]
N5["Síntese"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> Q["EX013"]
[5.1 Os documentos do engenheiro]
|
v
[5.2 Comunicando incerteza]
|
v
[5.3 Documentando componentes de IA]
|
v
[5.4 Públicos]
|
v
[5.5 Estrutura e rastreabilidade]
|
v
[Síntese]
|
v
[Exemplo resolvido] --> [Exercício EX013]
Objetivos de aprendizagem
Você vai (1) escrever documentos técnicos claros (requisitos, notas de projeto, relatórios de teste, resumos de incidentes); (2) comunicar incerteza e risco com honestidade; (3) adaptar mensagens a engenheiros, gestores e reguladores; e (4) documentar componentes de IA com model cards e datasheets.
5.1 Os documentos do engenheiro
Requisitos dizem o que um sistema deve fazer e o que não deve fazer. Notas de projeto explicam escolhas e alternativas. Relatórios de teste dizem o que foi testado, como, os resultados e os limites. Resumos de incidentes dizem o que aconteceu, o impacto, a causa e as ações. Cada um tem um leitor com uma decisão a tomar; escreva para essa decisão. Escrever para uma decisão muda o que vem primeiro. Um gestor que decide se implanta o TrackEye precisa do risco e das opções na primeira página; um testador que vai repetir a avaliação precisa do método completo. Sam abre cada documento com uma frase que nomeia o leitor e a decisão que o documento apoia, o que também lhe mostra o que pode ficar de fora.
5.2 Comunicando incerteza
Nunca escreva "o modelo é seguro". Escreva "nas condições testadas (lista), a taxa de falsos negativos foi de 2.1% (intervalo de 95% 1.6–2.7%); entre as condições não testadas estão neve intensa e marcações deliberadas". Números com intervalos e condições explícitas deixam os leitores julgarem por si mesmos. Separe fatos (medidos), avaliações (seu julgamento) e recomendações. O intervalo diz ao leitor quanto o número poderia variar se o teste fosse repetido com dados novos. Listar as condições não testadas é igualmente importante, porque, do contrário, os leitores supõem que o resultado as cobre. Manter fatos, avaliações e recomendações em parágrafos separados permite que um leitor que discorda de um julgamento continue confiando nas medições em que ele se apoia.
5.3 Documentando componentes de IA
Model cards (Mitchell et al., arXiv:1810.03993) descrevem o uso pretendido de um modelo, os usos fora de escopo, os dados de avaliação, as métricas desagregadas por fatores relevantes e as considerações éticas. Datasheets para conjuntos de dados (Gebru et al., arXiv:1803.09010) descrevem motivação, composição, coleta, pré-processamento, usos, distribuição e manutenção. Ambos tornam visíveis suposições ocultas para engenheiros e auditores a jusante. No TrackEye, o datasheet registra que a maioria das imagens de treinamento veio de viagens diurnas em via de bitola padrão, o que explica as fraquezas posteriores na madrugada e em tipos de trilho desconhecidos. Uma equipe que planeje reutilizar o modelo pode ver essa limitação antes de implantá-lo, em vez de descobri-la em serviço.
5.4 Públicos
Engenheiros precisam de interfaces precisas e modos de falha. Gestores precisam de risco, custo e opções. Reguladores e auditores precisam de evidências rastreáveis ligadas aos requisitos. O mesmo fato pode aparecer em três formas. O problema dos falsos negativos na madrugada mostra as três. Para engenheiros: os falsos negativos sobem para 9% entre 05:00 e 07:00 a 60–80 km/h, com o conjunto de teste nomeado. Para gestores: as inspeções de madrugada deixam passar mais defeitos, uma correção está em andamento e uma verificação manual provisória está em vigor. Para auditores: o achado, o requisito que ele afeta, o registro do teste e a ação corretiva, cada um com um identificador.
5.5 Estrutura e rastreabilidade
Numere os requisitos (REQ-SEC-012) e faça referência a eles nas notas de projeto e nos relatórios de teste, para que qualquer pessoa possa rastrear um requisito até sua evidência. Use tabelas para condições e resultados, figuras para tendências e parágrafos curtos para o raciocínio. Ponha a conclusão primeiro e o método depois para leitores que decidem; inverta a ordem para revisores que precisam conferir o método. Versione cada documento e mantenha um registro de mudanças: uma avaliação que era verdadeira para o modelo v1.3 pode ser falsa para o v1.4. Uma entrada do registro de mudanças diz o que mudou, por quê e quais resultados ela invalida.
5.6 Exemplo resolvido (caso sintético da NRS)
O primeiro relatório de teste do TrackEye escrito por Sam dizia "funciona bem na maioria das condições". O supervisor o devolveu. A versão revisada tinha um resumo de um parágrafo para gestores ("os falsos negativos de madrugada são 4.5× os diurnos; correção em andamento; provisoriamente: segunda verificação visual de madrugada"), uma tabela por condição com intervalos para engenheiros e uma seção de model card declarando os usos fora de escopo (não validado para trilhos de bonde nem para neve). O valor de 4.5× é a taxa de falsos negativos de madrugada, 9%, dividida pela diurna, 2%. A frase original não era falsa, mas não dava aos leitores nada sobre o que agir. A revisão permite que cada leitor encontre o que precisa sem ler o resto.
5.7 Erros e limites
Três erros são comuns: afirmações absolutas ("seguro", "safe") sem condições; misturar medição e opinião; e model cards escritos uma vez e nunca atualizados. Afirmações absolutas são tentadoras porque soam confiantes, mas um único contraexemplo as desfaz e, com elas, a confiança do leitor. Misturar medição e opinião torna impossível contestar uma sem a outra. Um model card que descreve a versão 1.3 anexado à versão 1.5 é pior do que nenhum, porque os leitores confiam nele; Sam vincula cada card a uma versão do modelo e o atualiza na mesma mudança que libera o modelo.
Exercícios
- EX013 — Reescrita. Reescreva "o Wrench está a salvo de injeção de prompt" como uma afirmação honesta. Rubrica: 3 = condições, métrica com intervalo, áreas não testadas; 2 = duas; 1 = uma; 0 = sem mudança.
- EX014 — Model card. Liste cinco seções de um model card para o TrackEye. Rubrica: 3 = cinco pertinentes; 2 = quatro; 1 = duas; 0 = nenhuma.
- EX015 — Públicos. Escreva o mesmo achado da madrugada para um gestor e para um auditor. Rubrica: 3 = gestor: risco/ação; auditor: evidência e vínculo com o requisito; 2 = um bom; 1 = vago; 0 = nenhuma.
Síntese
Uma comunicação clara e honesta — condições, intervalos, fatos separados das recomendações e modelos e conjuntos de dados documentados — é o modo como a evidência de engenharia chega a quem decide.
Continue estudando — capítulo 05 de 50
← Capítulo 04 (rascunho) · Índice de capítulos do curso · Capítulo 06 (rascunho) →