STE Simplify

¿Qué hace STE Simplify?

Descripción general

Produce explicaciones e instrucciones claras y sin ambigüedades utilizando un subconjunto práctico de ASD-STE100 Inglés Técnico Simplificado (STE).

Principio fundamental: Una palabra, un significado; una oración, una idea; voz activa, tiempo simple.

Este es un subconjunto de STE, no la especificación completa. No declare cumplimiento con ASD-STE100 en el resultado.

NO utilice esta skill para prosa creativa, de marketing o conversacional donde el estilo sea importante.

Conservar sin cambios

Copie estos elementos exactamente. Aplique las reglas solo a la prosa que los rodea:

• Código, comandos, rutas de archivo y valores entre comillas (por ejemplo 'localhost')
• Mensajes de error y cadenas de registro
• API, funciones, parámetros y nombres de variables
• Nombres de productos, nombres propios y números de versión
• Texto citado y texto legal
• Estructura Markdown al reescribir un documento: encabezados, enlaces, tablas y bloques de código. Reescriba la prosa dentro de los encabezados, elementos de lista y celdas de tabla, pero mantenga la misma estructura.

Mantener el significado

• Mantenga la acción y el objeto de cada oración. No agregue consejos, causas o pasos que la fuente no proporcione.
• El único contenido que puede agregar es una oración de definición de un término técnico (consulte Palabras).
• Para mostrar una posibilidad, escriba si, a veces, probablemente o puede. Nunca convierta una posibilidad en un hecho.
• Si una palabra simple pierde precisión, conserve la palabra original y defínala.
• Si la fuente tiene un término extraño o incorrecto, conserve la redacción de la fuente. Agregue una línea después del texto que comience con Nota: e indique el problema. No lo corrija en silencio.
• Si la fuente tiene un etc. colgante sin una lista antes, elimínelo.

Reglas

1. Palabras

• Una palabra, un significado. Use la misma palabra para la misma cosa en todo el texto. No cambie el nombre de una cosa.

• Elija la palabra simple:

  Use	En lugar de
  usar	utilizar, emplear, aprovechar
  iniciar	comenzar, empezar
  detener	cesar, terminar, interrumpir
  mostrar	demostrar, indicar, ilustrar
  cambiar	modificar, alterar
  asegurarse	garantizar, cerciorarse
  ayudar	facilitar, asistir
  necesitar, debe	requerir, ser necesario
  si	siempre que, en caso de que
  porque	debido a que, ya que, puesto que (cuando dan una razón; desde es correcto para tiempo)

• Sin modismos, jerga, metáforas o analogías. Explique con la cosa misma.

• Sin contracciones. Escriba no, no no.

• Escriba por ejemplo, es decir y y así sucesivamente en lugar de p.ej., es decir y etc.

• Defina un término técnico en una oración en el primer uso si un lector nuevo en el tema no lo conocería (por ejemplo demonio, registro de escritura anticipada). No defina nombres que deba conservar.

2. Sustantivos

• Máximo 3 sustantivos en un grupo. Separe grupos más largos con preposiciones.
  • Malo: "Ejecute la verificación de estado del grupo de conexiones de la base de datos de producción."
  • Bueno: "Verifique el estado del grupo de conexiones para la base de datos de producción."
• Mantenga los artículos (el, la, los, las, un, una).

3. Verbos

• Voz activa. Nombre quién o qué realiza la acción.
  • Malo: "El archivo de configuración es leído por el servidor."
  • Bueno: "El servidor lee el archivo de configuración."
• Modo imperativo para instrucciones.
  • Malo: "Debe reiniciar el servicio."
  • Bueno: "Reinicie el servicio."
• Tiempos simples. Use presente simple, pasado simple y futuro simple (leerá). No use formas progresivas (está leyendo) o perfectas (ha leído). Ha y han son correctos como verbos principales (la cuenta tiene un saldo).
• Modales: No use habría, podría o pudiera. Use puede solo para mostrar posibilidad. Use poder solo para mostrar habilidad. Cambie debería a un imperativo, o a debe si la acción es obligatoria.
  • Malo: "Debería hacer una copia de seguridad de la base de datos antes de la actualización."
  • Bueno: "Haga una copia de seguridad de la base de datos antes de la actualización."
• Sin gerundio como sustantivo. Un participio como adjetivo es correcto (el proceso en ejecución).
  • Malo: "Registrar errores ayuda a depurar."
  • Bueno: "Registre los errores en el registro para ayudar a encontrar fallos."

4. Oraciones y párrafos

• Descripciones: Máximo 25 palabras por oración. Una idea por oración.
• Instrucciones: Máximo 20 palabras por oración. Una instrucción por oración, a menos que dos acciones ocurran al mismo tiempo. Este límite también aplica a cada elemento de una lista numerada de pasos.
• Texto mixto: Aplique el límite de 20 palabras a cada instrucción que le indique al lector que actúe. Aplique el límite de 25 palabras a todo lo demás, incluidos los pasos en una descripción de cómo funciona un sistema.
• Condición primero.
  • Malo: "Elimine el archivo de bloqueo si el proceso se detiene."
  • Bueno: "Si el proceso se detiene, elimine el archivo de bloqueo."
• Máximo 6 oraciones por párrafo. Un tema por párrafo.
• Use una lista vertical para 3 o más elementos o para pasos secuenciales.

5. Advertencias

• Si un paso puede causar lesiones, pérdida de datos o daños, coloque una línea corta de Advertencia: antes de ese paso. Indique el riesgo.
• Si un riesgo aplica a varios pasos, escriba una línea de Advertencia: antes del primero de esos pasos.

Estructura de salida

Para explicar un concepto (use estos encabezados en este orden; omita una sección opcional según indique su regla):

1. Definición: 1–2 oraciones. Indique qué es y qué hace.
2. Cómo funciona: Incluya solo si el concepto tiene un proceso ordenado. Use una lista numerada de oraciones cortas.
3. Términos clave: Enumere cada término técnico en el texto que un lector nuevo no conocería, excepto el término principal que la Definición ya define. Defina cada uno en una oración. Omita esta sección si la lista está vacía.
4. Ejemplo: Un ejemplo concreto y mínimo. Máximo 5 oraciones o pasos.

Para reescribir texto existente: Genere solo el texto reescrito, más una línea Nota: si la regla Mantener el significado lo requiere. No use encabezados. Use una lista vertical para los pasos. No agregue un prefacio o una lista de cambios a menos que el usuario lo solicite.

Nivel del lector: Si el usuario dice que el lector es un novato o principiante, defina cada término técnico y use la sección de Términos clave. Si el usuario no da ningún nivel, asuma que el lector conoce los conceptos básicos del campo. Explique la idea específica, no todo el campo.

Ejemplos

Reescribir texto existente

Fuente:

El mecanismo de control de promoción de artefactos de la tubería de implementación se está utilizando para garantizar que las compilaciones que no han sido validadas por QA no se propaguen a producción.

Reescritura:

La tubería bloquea las compilaciones que QA no validó. Solo las compilaciones validadas van a producción.

Explicar un concepto

Solicitud: "Explica qué es un índice de base de datos."

Definición: Un índice de base de datos es una estructura de datos que ayuda a la base de datos a encontrar filas rápidamente. La base de datos mantiene el índice además de la tabla.

Cómo funciona:

1. La base de datos copia los valores de una o más columnas en el índice.
2. La base de datos ordena estos valores y almacena un puntero a cada fila.
3. Una consulta busca los valores ordenados en lugar de cada fila de la tabla.

Términos clave:

• Columna: Un campo con nombre en cada fila de una tabla.
• Puntero: Un valor que da la ubicación de una fila.

Ejemplo: Una tabla usuarios tiene un millón de filas. Agrega un índice en la columna correo. Una consulta para una dirección de correo ahora lee solo unas pocas entradas de índice. Sin el índice, la consulta lee el millón de filas.

Autoverificación antes de responder

Lea su borrador una vez y corrija cada infracción:

• ¿Una descripción de más de 25 palabras, o una instrucción o paso de lista de más de 20 palabras? Divídalo.
• ¿Voz pasiva, tiempo progresivo o perfecto, habría/podría/pudiera, o debería? Reescríbalo.
• ¿Un gerundio usado como sustantivo? Use un verbo simple.
• ¿Un grupo de más de 3 sustantivos? Sepárelo con de, para, en o a.
• ¿Una contracción, un modismo, una analogía, o p.ej., es decir, etc.? Reemplácelo.
• ¿Una palabra de la columna En lugar de de la tabla? Use la palabra de la columna Use.
• ¿Un hecho, paso o causa que la fuente no contiene? Elimínelo.
• ¿Texto protegido (código, nombres, errores, valores entre comillas, estructura Markdown) cambiado? Restáurelo exactamente.
• ¿Una cosa con dos nombres? Elija uno.