¿Qué hace Pasos de turno nocturno?
Qué es esto
La mayoría de los procedimientos están escritos por la persona que ya conoce el trabajo. Se leen bien en un escritorio. Fallan a las 3 a. m., en una sala ruidosa, en un teléfono, en un segundo idioma, o cuando el lector tiene miedo de romper algo. Los fallos son predecibles: dos acciones ocultas en un paso, una advertencia que está después del paso que protege, una condición que aparece al final de la oración, una oración pasiva que oculta quién debe actuar, y palabras como "adecuadamente" que piden al lector que adivine.
Esta habilidad convierte ese texto en pasos que una persona puede seguir literalmente. Toma prestada la disciplina de los lenguajes controlados utilizados en el mantenimiento de aeronaves e industrial (oraciones cortas, una acción por oración, voz activa, una palabra para una cosa), el orden de los mensajes de seguridad utilizado en las etiquetas de los equipos (palabra de señal, peligro, consecuencia, evitación), y el hábito de escribir un resultado esperado después de cada paso riesgoso para que el lector sepa cuándo detenerse.
No es un pase de "hazlo sonar humano". El objetivo es un procedimiento que no pueda malinterpretarse, aunque suene un poco simple.
Cuándo usarlo
- Runbooks, manuales de incidencias, listas de verificación de guardia, pasos de despliegue y reversión.
- Guías de configuración o reparación de hardware, dispositivos domésticos, equipos de laboratorio o TI de oficina.
- Procedimientos operativos estándar (POE) y notas de traspaso para otra persona o turno.
- Instrucciones que serán traducidas automáticamente o leídas por hablantes no nativos.
- Cualquier texto donde un paso mal leído pueda perder datos, dinero o causar lesiones.
No lo uses para ensayos, textos de marketing o explicaciones conceptuales. Esos necesitan una voz diferente.
Las reglas (nivel predeterminado)
| # | Regla | Límite o prueba |
|---|---|---|
| R1 | Una acción por paso | Sin ", luego", "y luego", ";" o dos verbos unidos por "y" dentro de un paso |
| R2 | Oraciones de instrucción cortas | 20 palabras en español, unas 35 caracteres en chino |
| R3 | Oraciones descriptivas cortas | 25 palabras en español, unas 45 caracteres en chino |
| R4 | Voz imperativa y activa | Empieza con el verbo. Nombra al actor si no es el lector |
| R5 | Condición primero | "Si la luz está roja, detente." nunca "Detente si la luz está roja." |
| R6 | Una palabra, un significado | Fija los términos en un glosario. Nunca intercambies sinónimos por variedad |
| R7 | Valores exactos | Números con unidades, etiquetas exactamente como se muestran en pantalla o dispositivo |
| R8 | Mensaje de seguridad antes del paso | Palabra de señal, peligro, consecuencia, qué hacer |
| R9 | Resultado esperado después de pasos riesgosos | "Resultado: ..." y qué hacer si el resultado es diferente |
| R10 | Sin palabras de adivinanza | Elimina "adecuadamente", "según sea necesario", "asegúrate", "debería", "solo" |
Nivel estricto (para texto crítico para la seguridad o regulado): aplica todas las reglas sin excepciones, no permitas ninguna ambigüedad, y pon una línea de Resultado después de cada paso. Nivel ligero (para una nota interna que ya es decente): aplica solo R1, R5, R8 y R9.
Palabras de señal
Usa la palabra más baja que siga siendo cierta. No infles.
- PELIGRO: causará la muerte o lesiones graves si se ignora.
- ADVERTENCIA: puede causar la muerte, lesiones graves o la pérdida de datos o dinero importantes.
- PRECAUCIÓN: puede causar lesiones menores o daños que puedas reparar.
- AVISO: sin riesgo de lesiones; solo riesgo de propiedad, datos o tiempo.
Cada mensaje de seguridad tiene tres partes: cuál es el peligro, qué sucede si el lector lo ignora y qué hacer. "Ten cuidado" no es un mensaje de seguridad.
Cómo trabajar
- Completa la tarjeta del procedimiento. Antes de editar, escribe: el estado objetivo ("Disco 2 reconstruyendo"), quién lo seguirá (rol, idioma, condiciones como guantes, ruido, pantalla de teléfono, noche), qué tienen (acceso, herramientas, tiempo), los peligros y las condiciones de parada. Pregunta al usuario cualquier cosa que no puedas inferir. Una condición de parada faltante es la brecha más común.
- Enumera los hechos que debes conservar. Cada número, unidad, etiqueta, comando, restricción de orden, advertencia y condición. La reescritura debe contenerlos todos y no añadir ninguno. Si crees que un valor es incorrecto, márcalo; no lo corrijas en silencio.
- Divide en acciones. Un verbo que hace el lector = un paso. La navegación cuenta ("Ir a Almacenamiento" y "Seleccionar Disco 2" son dos pasos). Mueve el contexto a un breve párrafo "Antes de empezar".
- Reescribe cada paso. Verbo primero, condición primero, etiquetas exactas en negrita o
código, unidades siempre. Reemplaza toda pasiva que oculta un actor: "La clave se genera" se convierte en "La herramienta genera la clave" o, mejor, el paso que da el lector para generarla. - Coloca los mensajes de seguridad. Para cada paso que borra, sobrescribe, apaga, reinicia, desconecta, calienta, corta o presuriza, pon el mensaje directamente encima del paso. Elige la palabra de señal de la escalera anterior.
- Añade resultados y salidas. Después de cada paso riesgoso o que cambie el estado, escribe lo que el lector ve cuando funcionó. Si el resultado puede diferir, da una línea: "Si ves X, detente y ve a la Recuperación A." Escribe las secciones de recuperación.
- Fija el glosario. Elige un término por cosa (por ejemplo "bandeja", no "caddy" ni "sled"). Guárdalo como
glossary.jsonsi el procedimiento se va a mantener. - Lint. Ejecuta
python scripts/stepcheck.py lint procedure.md --glossary glossary.json. Corrige todos los hallazgos UNSAFE y REWORK, o explica por qué uno es un falso positivo. - Haz un recorrido literal. Lee solo los pasos numerados, como alguien que hace exactamente lo que dice cada oración y nada más. ¿Dónde se detendrían, adivinarían o harían algo dañino? Corrige esos lugares.
- Devuelve el procedimiento reescrito, luego una lista breve de cambios (números de reglas), la lista de hechos que no pudiste verificar y preguntas abiertas.
El script de ayuda
scripts/stepcheck.py es un linter Python de la biblioteca estándar para procedimientos en Markdown, en español o chino.
| Código | Gravedad | Significado |
|---|---|---|
| HAZARD-NO-WARNING | hard | Un paso riesgoso no tiene un mensaje de seguridad encima |
| LATE-WARNING | hard | El mensaje de seguridad está después del paso que protege |
| WEAK-WARNING | fix | El mensaje no dice qué sucede |
| LONG | fix | Oración de instrucción sobre el límite |
| STACKED | fix | Más de una acción en un paso |
| HIDDEN-ACTOR | fix | Voz pasiva o 被 oculta quién actúa |
| HEDGE / VAGUE | fix | Palabras de adivinanza |
| CONDITION-LAST | fix | La condición viene después de la acción |
| DRIFT | fix | Un sinónimo prohibido del glosario |
| NO-RESULT, LONG-DESC | note | Solo consejo |
Veredicto: READY (código de salida 0), REWORK (código de salida 1), UNSAFE (código de salida 2). El script usa listas de palabras y patrones, por lo que se salta cosas y a veces marca una oración correcta. Nunca reemplaza el paso 9.
Ejemplo
Antes:
- Apaga el NAS si todavía está funcionando.
- Saca la bandeja del Disco 2 y pon el disco nuevo en ella. PRECAUCIÓN: El disco viejo puede estar caliente.
Después:
ADVERTENCIA: Apaga el NAS antes de extraer un disco. Un disco extraído mientras funciona puede dañar el segundo disco. 5. Presiona el botón de encendido durante 2 segundos para apagar el NAS. Resultado: Todas las luces del frente se apagan después de aproximadamente 1 minuto. PRECAUCIÓN: El disco viejo puede estar caliente tras el uso. Sujétalo por la bandeja, o puedes quemarte los dedos. 6. Saca la bandeja del Disco 2. 7. Pon el disco nuevo en la bandeja.
Cambios: R1 (paso 4 dividido), R5 (condición eliminada al convertir el apagado en su propio paso), R8 (advertencia movida hacia arriba y con consecuencia), R9 (resultado añadido). Los archivos completos están en examples/.
Consejos
- Si el texto fuente está mal, la reescritura más clara sigue estando mal. Marca los valores dudosos en la lista de cambios.
- Mantén los comandos, las rutas y las etiquetas en pantalla byte por byte. Una prosa clara alrededor de un comando mal escrito es peor que el original.
- Un paso que necesita una explicación larga suele ser dos pasos más una nota antes de ellos.
- Numera los pasos de forma continua. No reinicies la numeración dentro de un procedimiento; usa secciones separadas para la recuperación.
- Lee las versiones en español y chino una al lado de la otra cuando produzcas ambas: cada paso debe corresponder uno a uno.
- Nunca afirmes que el resultado cumple con algún estándar de lenguaje controlado oficial. Di "escrito en un estilo controlado".