Escritura
Un texto técnico claro: acción, condición y comprobación
Cómo escribir instrucciones y descripciones de proyectos para que el lector entienda la tarea y el siguiente paso.
Una buena instrucción ayuda a realizar una acción y comprobar el resultado. Una buena descripción de proyecto permite entender la tarea, la función del autor y el estado actual. Un texto breve solo resulta útil si conserva la información necesaria.
En esta práctica combino principios de lenguaje claro, la escritura técnica de ASD-STE100 y el enfoque de William Zinsser. Es una base editorial. No afirma que los textos rusos ni sus traducciones cumplan un estándar de inglés. Su vocabulario controlado y sus restricciones gramaticales no se pueden trasladar de forma mecánica a otros idiomas.
Empiece por la tarea del lector
Antes de editar, responda a tres preguntas: quién necesita el texto, qué debe entender y qué podrá hacer después de leerlo. Si la instrucción se dirige a una persona en prácticas, explique el nombre de la herramienta. Para un especialista con experiencia, puede bastar una guía breve.
En lugar de «Mire la solicitud en DevTools», indique los pasos del navegador elegido: «En Chrome para Windows, pulse F12. Abra la pestaña Network. Repita la acción en la página y busque la solicitud». Después, indique qué campo o valor debe comprobar. Los nombres de los elementos pueden cambiar; contrástelos con la versión y el idioma utilizados.
Indique la acción y quién la realiza
«Se realiza una comprobación de los ajustes» no indica quién comprueba ni qué debe revisar. Es más claro: «Antes de iniciar el proceso, el administrador comprueba la dirección del servicio y los permisos de la cuenta». Si es un paso de una instrucción, use una orden directa: «Compruebe la dirección del servicio».
Cada instrucción suele contener una acción. Coloque antes de la acción la condición que modifica el procedimiento: «Si la solicitud devuelve un error, guarde su código. Después consulte el registro». No elimine una condición solo para acortar la frase.
Utilice términos coherentes
Elija un nombre para cada entidad. Si la interfaz indica «Sala de reuniones», no llame al mismo objeto sala, recurso o espacio en pasos consecutivos. Explique un término técnico la primera vez que aparezca y utilícelo después de forma coherente.
Un enlace debe nombrar el documento o el resultado esperado. «Documentación de la API» aporta más que «aquí». Conserve exactamente el código, las rutas, los identificadores y los nombres de los botones. No los cambie para mejorar el estilo.
Separe la función del resultado
Al describir su experiencia, indique qué hizo personalmente, qué hizo el equipo y qué sigue en curso. «Aclaré los requisitos y participé en el cambio de arquitectura. El equipo implementó los procesos principales» conserva los límites de cada aportación.
Un plan de implementación no equivale a una implementación terminada. No presente el alcance previsto como un resultado. Si utiliza una imagen literaria, identifíquela como tal y añada junto a ella una descripción de los hechos.
Tenga en cuenta la traducción
El objetivo es el mismo en ruso, inglés, alemán y español: el lector encuentra lo que necesita, comprende las condiciones y ve el siguiente paso. Utilice la gramática natural de cada idioma. No reproduzca literalmente la estructura de una frase rusa.
Evite expresiones cuyo sentido dependa de una broma local o de un modismo. Conserve el vocabulario del producto, los números de versión y los enlaces. Compruebe la longitud de las etiquetas: un menú alemán suele necesitar más espacio. Un texto claro para el público general y la lectura fácil con reglas específicas son tareas diferentes.
Compruebe el texto mientras se utiliza
Entregue la instrucción a una persona que no conozca la tarea. Pídale que encuentre el paso necesario y explique el resultado. Anote sus preguntas. Si entiende las palabras pero no sabe qué hacer, aclare el contenido; no se limite a acortar las frases.
La descripción de un proyecto requiere otra comprobación: ¿puede el lector identificar la tarea, su función y el estado sin explicaciones adicionales? Si no, corrija primero esas partes.
Fuentes
- ASD-STE100: propósito y límites.
- William Zinsser: Writing English as a Second Language.
- Google: escritura para una audiencia internacional.
Las reglas editoriales de este sitio se basan en la guía «La claridad como herramienta de trabajo», proporcionada por el autor y fechada el 3 de octubre de 2026.