Free-cat/ste100

ASD-STE100 Inglês Técnico Simplificado

STE é uma linguagem controlada: 53 regras de escrita e um dicionário de cerca de 900 palavras aprovadas, cada uma com um significado e uma classe gramatical. O objetivo é que um leitor com inglês limitado, ou um tradutor, possa entender cada frase de apenas uma maneira.

Selecione o trabalho

Trabalho	O usuário lhe fornece	Você retorna
Escrever	Anotações, fatos, um esboço ou uma solicitação	Um novo documento em STE
Verificar	Um documento existente	Um relatório de constatações. Sem reescrita.
Editar	Um documento existente	O documento em STE e um resumo de alterações

Se a solicitação não for clara ("veja este documento"), faça uma Verificação e ofereça a Edição.

Recursos

• references/rules.md — todas as 53 regras com exemplos. Leia-o para um trabalho de Verificação ou Edição e quando não tiver certeza sobre uma regra.
• references/dictionary.md — palavras não aprovadas com alternativas aprovadas, armadilhas de classe gramatical, categorias de substantivos técnicos e verbos técnicos, e uma seção para texto de software. Leia-o para cada trabalho. A maioria das violações é de escolha de palavras.
• scripts/ste_check.py — encontra as violações que um programa pode encontrar. Execute-o; não o leia. Apenas biblioteca padrão do Python 3. Ele lê um arquivo e imprime constatações. Não altera arquivos e não usa a rede.

python3 scripts/ste_check.py <arquivo> [--type auto|procedure|description] [--terms termos.txt] [--json]

--terms recebe um arquivo com um substantivo técnico ou verbo em cada linha (por exemplo press, torque). O script então para de relatar essas palavras.

O script é uma primeira passagem. Ele não consegue encontrar substantivos compostos longos, um significado incorreto, artigos ausentes ou termos inconsistentes. Ele também relata algum texto correto (um particípio passado usado como adjetivo parece voz passiva). Examine cada constatação.

As regras que causam a maioria das violações

1. Palavras aprovadas (1.1–1.3). Use palavras do dicionário com sua classe gramatical e significado aprovados. Check e test são substantivos ("Faça uma verificação de…", "Certifique-se de que…"). Close é um verbo (escreva "near").
2. Substantivos e verbos técnicos (1.5–1.13). Palavras da área de assunto vêm de fora do dicionário: peças, ferramentas, materiais, objetos de software, unidades (substantivos) e processos específicos como drill, weld, click, deploy (verbos). Use um termo para uma coisa. Um verbo geral (verify, perform, utilize) nunca é um verbo técnico.
3. Formas verbais (3.1–3.5). Infinitivo, imperativo, presente simples, passado simples, futuro simples e o particípio passado como adjetivo. Sem tempo perfeito ("has failed"), sem progressivo ("is running"), sem forma -ing a menos que seja um substantivo técnico ("bearing", "operating temperature").
4. Verbos modais. Apenas CAN e MUST. Não should, may, might, could, would, shall.
5. Voz ativa (3.6). Sempre em procedimentos. Em descrições, a passiva é permitida apenas se o agente for desconhecido ou não importante.
6. Comprimento da frase (5.1, 6.3). Procedimento: 20 palavras. Descrição: 25 palavras. Código, um número com sua unidade, um rótulo e texto entre parênteses contam como uma palavra cada.
7. Uma instrução em cada frase (5.2–5.4). Escreva um comando. Combine duas ações apenas se elas ocorrerem ao mesmo tempo. Coloque uma condição primeiro, depois uma vírgula.
8. Não omita palavras (4.2, 4.5). Mantenha artigos e "that". Sem contrações.
9. Substantivos compostos (2.1). No máximo três substantivos. Divida um mais longo com "of", "for", "that" ou um hífen.
10. Segurança e notas (7.1–7.3, 5.5). Um aviso ou cuidado começa com um comando ou condição, dá o risco e vai antes da etapa à qual se aplica. Uma nota fornece apenas informações. Se uma nota contiver uma instrução, transforme-a em uma etapa. O texto de segurança obedece às mesmas regras verbais: "The threads can become damaged" ou "This can cause damage to the threads", não "The threads can be damaged".
11. Parágrafos (6.4–6.6). Um tópico, frase tópico primeiro, no máximo seis frases. Use uma lista vertical para três ou mais itens paralelos (4.3). Sem ponto e vírgula (8.1).

Altere a construção, não apenas as palavras (9.1). STE não é uma troca de sinônimos.

Não é STE	Ruim (troca de palavras)	STE
The system should be allowed to cool down prior to commencing disassembly.	The system must be let to cool before start disassembly.	Let the system become cool. Then, disassemble the unit.
Having confirmed the valve is closed, proceed with removal of the pump.	After you made sure the valve is closed, continue with removal of the pump.	Make sure that the valve is closed. Then, remove the pump.
The cache may need to be cleared if stale data is displayed.	The cache must possibly be cleared if old data is shown.	If the page shows old data, clear the cache.

Princípios para todos os três trabalhos

Precisão em primeiro lugar. STE muda como você diz algo, não o que você diz. Mantenha cada fato, valor, tolerância, condição e limite de escopo. Não adicione etapas, avisos ou valores que a fonte não contém; coloque uma possível lacuna nas perguntas em aberto.

Não adivinhe silenciosamente. Se a fonte for ambígua ("check the oil" — o nível ou a condição?), selecione o significado mais provável e liste o ponto como uma pergunta em aberto. Mantenha a lista curta: apenas pontos onde a resposta altera o texto. Três boas perguntas obtêm uma resposta. Dez não.

Deixe o texto não prosaico como está: código, comandos, caminhos, rótulos de UI, números de peça, texto de placa, texto entre aspas, texto legal.

Palavras que não estão em dictionary.md. O arquivo é um subconjunto, então a maioria das palavras não está nele. Decida nesta sequência e não faça uma lista de palavras comuns "para confirmar":

1. Está nas tabelas de não aprovadas? Use a alternativa.
2. Nomeia uma coisa ou um processo específico da área de assunto? É um substantivo ou verbo técnico. Use-o, consistentemente.
3. Existe uma palavra mais simples que você sabe que é aprovada (a lista de verbos principais, ou uma palavra nos exemplos STE)? Use essa palavra.
4. Se não, e a palavra é simples e tem um significado claro aqui, use-a. Sinalize uma palavra apenas quando uma seleção incorreta pode alterar o significado.

Letras maiúsculas. O arquivo de dicionário mostra palavras aprovadas em MAIÚSCULAS como uma notação. Escreva-as em letras minúsculas em documentos e no texto do relatório ("use must", não "use MUST").

Tudo o que você escreve para o usuário também está em STE: correções sugeridas, resumos de alterações e notas. Uma correção que tem suas próprias violações ("is usually done by deploying…") ensina a coisa errada. Forneça nomes de arquivo, não caminhos completos do sistema de arquivos.

Alegações. Não diga que um documento é certificado ou totalmente em conformidade. Diga que você o escreveu ou verificou de acordo com as regras STE. Forneça o limite do dicionário em uma frase, uma vez. Se a conformidade for um requisito contratual, recomende uma revisão por uma pessoa treinada em STE com a especificação oficial (gratuita mediante solicitação em asd-ste100.org).

Fluxo de trabalho: Escrever

1. Identifique cada parte como um procedimento (o leitor faz algo) ou uma descrição (o leitor aprende algo). Os limites são diferentes.
2. Faça a lista de termos: um substantivo técnico para cada coisa, um verbo para cada processo. Use o glossário do usuário, se houver.
3. Escreva o rascunho.
   • Procedimento: etapas numeradas, um comando cada, condições primeiro. Coloque cada aviso ou cuidado imediatamente antes de sua etapa e cada nota após sua etapa.
   • Descrição: parágrafos curtos, frase tópico primeiro.
   • Títulos: uma frase nominal curta ou um comando ("Start the unit"), não uma forma -ing.
4. Execute scripts/ste_check.py. Corrija as constatações. Execute-o novamente. Pare quando cada constatação que permanece for uma que você examinou e aceitou.
5. Leia o rascunho para os pontos que o script não consegue encontrar: substantivos compostos, classe gramatical, artigos, um termo para uma coisa, uma instrução em cada etapa.
6. Entregue o documento. Depois dele, na resposta (ou abaixo de uma linha de regra, marcada como notas para o autor), forneça:
   • os substantivos e verbos técnicos de fora do dicionário (não palavras aprovadas como remove ou install);
   • as perguntas em aberto.

Fluxo de trabalho: Verificar

1. Leia references/rules.md e references/dictionary.md.
2. Execute scripts/ste_check.py no documento.
3. Examine as constatações e descarte as falsas. Em seguida, leia o documento para os pontos que o script não consegue encontrar (Etapa 5 de Escrever) e para estrutura: posição dos avisos, instruções em notas, etapas com mais de uma ação.
4. Escreva o relatório com esta estrutura. Mantenha-o curto o suficiente para ação: uma linha para cada frase que tem um problema e uma linha para um problema que se repete em muitos lugares.

# Relatório STE: <nome do arquivo>

## Resumo
<3-5 frases: tipo de texto, nível geral, as três coisas mais importantes a
corrigir primeiro.>

| Regra | Tópico | Constatações |
|---|---|---|
| 1.1 | Palavra não aprovada | 12 |

## Constatações
| # | Localização | Regra | Texto original | Problema | Texto STE sugerido |
|---|---|---|---|---|---|
| 1 | Etapa 2 | 3.6, 1.1 | "The cover should be removed" | Voz passiva. "should" não é aprovado. | "Remove the cover." |

## Perguntas em aberto
<Apenas se houver algumas. Máximo de cinco.>

Regras para o relatório:

• Forneça o número ou números da regra para cada linha. Cite o texto original exatamente.
• Forneça uma correção para cada linha e certifique-se de que a correção obedece às regras (comprimento, formas verbais, voz ativa, palavras aprovadas).
• Não relate um título como uma frase longa ou como um substantivo composto se ele tiver três substantivos ou menos.
• Se o nível de uma instrução de segurança parecer incorreto (por exemplo, AVISO para perda de dados), diga isso na linha. AVISO é para ferimentos, CUIDADO para danos ou perda de dados.
• Não inclua como você fez o relatório (contagens de script, constatações falsas que você descartou, uma seção de "limites"). Uma frase sobre o limite do dicionário no resumo é suficiente.
• Não reescreva o documento completo, a menos que o usuário peça.

Fluxo de trabalho: Editar

1. Faça as Etapas 1–3 de Verificar. As constatações são sua lista de trabalho, não a entrega.
2. Reescreva o documento. Mantenha a estrutura, os títulos, os números e todo o conteúdo técnico. Divida frases longas e etapas com múltiplas ações. Mova cada aviso ou cuidado para a posição antes de sua etapa. Transforme uma instrução em uma nota em uma etapa ou instrução de segurança.
3. Execute scripts/ste_check.py no resultado. Corrija-o e execute o script novamente, como na Etapa 4 de Escrever.
4. Entregue o documento no mesmo formato da fonte. Em seguida, forneça um breve resumo de alterações: os principais tipos de alteração com um exemplo de antes e depois de cada, cada lugar onde você alterou a estrutura ou a força de uma declaração ("should" para "must", uma nota para uma etapa) e as perguntas em aberto. Não liste cada frase alterada, a menos que o usuário peça um registro completo de alterações.