Cómo escribir instrucciones paso a paso claras para software

Unas instrucciones de software claras permiten al lector terminar una tarea sin tener que pensar en las instrucciones. Cada palabra de más, cada etiqueta vaga y cada paso combinado lo obliga a detenerse y releer.

Este artículo recoge las reglas de redacción más importantes, con ejemplos, y explica cómo se aplican cuando creas una guía en Temposhot en un Mac.

Define un resultado terminado

Escribe primero el resultado, en una frase que el lector pueda comprobar: "La factura se envía al cliente y se marca como Sent". Esa frase se convierte en el título y en el último paso.

Si no puedes escribir un solo resultado, las instrucciones cubren más de una tarea. Sepáralas. Un lector que busca "send an invoice" no quiere leer hasta llegar a "create a customer".

Escribe el resultado antes de la primera captura. Un resultado escrito después de la captura tiende a describir la grabación, con cada clic que el autor hizo por casualidad. Un resultado escrito primero decide qué clics pertenecen a la guía. Los clics que solo cambian de pantalla, como abrir un menú para llegar a la página correcta, normalmente se pueden sustituir por una sola etiqueta que nombre el destino.

Cuando una tarea implica dos roles, escribe dos guías con un resultado cada una. Una guía para la persona que aprueba una factura y otra para la que la envía tienen puntos de partida y comprobaciones distintos. Unirlas obliga a cada lector a saltarse las partes que no corresponden a su rol.

Un resultado vago y un resultado comprobable

Un resultado es comprobable cuando el lector puede mirar la pantalla y responder sí o no. La comparación siguiente muestra la misma tarea escrita de dos maneras.

La versión comprobable también fija la longitud de la guía. Una guía que termina con un estado visible tiene un último paso natural, así que el autor no añade un párrafo final que repita el primero.

Empieza cada paso con la acción

Los lectores buscan el verbo. Ponlo al principio.

Débil	Claro
The Settings menu should now be opened.	Open Settings.
Next, you will want to click on Save.	Select Save.
In the top-right corner there is a Share button.	Select Share in the top-right corner.
Make sure that notifications are turned off.	Turn off Notifications.

Mantén una lista corta de verbos y úsala de forma coherente: Open, Select, Choose, Enter, Turn on, Turn off, Drag. "Click" funciona para los usuarios de ratón, pero falla para los usuarios de teclado y táctiles, así que muchas guías de estilo prefieren "Select".

Usa la forma imperativa en cada paso. "Select Save" y "Open Settings" indican al lector lo que debe hacer ahora. "You should select Save" añade una capa que el lector tiene que quitar antes de actuar. La misma regla se aplica a la frase de resultado al final de un paso, que describe lo que muestra la pantalla: "The banner shows Changes saved."

Un verbo para cada tipo de control

Una lista de verbos solo funciona cuando cada verbo corresponde a un tipo de control. Un lector que ve "Choose" espera una lista o un menú, y uno que ve "Select" espera un botón o un enlace. La lista de comprobación siguiente da una regla para cada verbo.

Cuando un control no corresponde a ningún verbo de la lista, describe su ubicación y su etiqueta. Un control que abre un selector es "Choose", y un control que inicia un proceso es "Select". Mantén la lista corta, porque cada verbo nuevo es una regla más que el redactor tiene que recordar.

Usa etiquetas exactas de la interfaz

Copia las etiquetas exactamente como las muestra la interfaz, incluidas las mayúsculas y la puntuación. Si el botón dice Add member, no escribas "Add a user". Los lectores buscan las palabras que ven en pantalla.

Pon la etiqueta en negrita para que destaque de la frase. Indica la ubicación solo cuando la etiqueta sea difícil de encontrar o aparezca dos veces: "Select Export in the toolbar, not in the File menu."

Etiquetas que aparecen dos veces

Una etiqueta que aparece en dos lugares lleva al lector al equivocado cuando el paso solo nombra la etiqueta. Un cuadro de diálogo a menudo repite el botón de la barra de herramientas con la misma palabra, así que un paso que dice solo "Select Export" puede leerse como cualquiera de los dos controles. La solución es nombrar el lugar al que se refiere el paso e indicar lo que debe ver el lector a continuación. "Select Export in the toolbar. The export dialog opens." La segunda frase confirma que el lector tiene el control correcto antes de seguir.

Los menús añaden un segundo problema. Un elemento de menú llamado Settings puede existir en el menú de la app y en la barra de la ventana. Escribe la ruta solo cuando el lector la necesite, y escríbela una sola vez, en el paso que usa el menú por primera vez.

Reglas de etiquetas para la búsqueda del lector

Un lector que no encuentra una etiqueta suele buscar en la pantalla el texto exacto. Una paráfrasis lo lleva al lugar equivocado o a ningún lugar. La tabla siguiente muestra las reglas en uso.

Una etiqueta que cambia entre versiones de la app necesita una nota. Indica la versión en la descripción de la página, por ejemplo "In version 4, the button reads Invite.". La nota elimina la pregunta antes de que el lector la haga.

Mantén una decisión por paso

Un paso debe contener una acción o una elección. "Open Settings, select Billing, and change the plan" son tres pasos. Cuando el lector vuelve a mirar la pantalla, pierde el hilo en una frase larga.

Excepción: dos acciones en la misma zona pequeña que siempre van juntas, como "Enter the code and select Verify". Incluso así, sepáralas si la segunda acción tiene una condición.

Los pasos de decisión requieren el mismo cuidado. Cuando el lector debe elegir entre opciones, enumera las opciones en el paso o nombra el ajuste que controla la elección. "Choose a format" obliga al lector a adivinar las opciones. "Choose PDF or PNG in Format. Choose PDF for print" da una regla que el lector puede aplicar sin releer.

Divide un paso compuesto

Un paso compuesto suele ocultar un punto de decisión. El ejemplo siguiente parte de un único paso que cambia una suscripción y lo divide en cada acción que el lector debe confirmar.

La primera versión de la frase tenía seis verbos y una confirmación. Los cuatro pasos anteriores tienen una acción cada uno, y el último paso contiene un punto de control, que trata la sección siguiente.

Añade puntos de control después de las acciones importantes

Después de una acción que cambia algo, indica al lector lo que debe ver: "A green banner shows Changes saved.". Los puntos de control confirman el avance y detectan los errores pronto, antes de que el lector esté cinco pasos más adelante.

Coloca los puntos de control después de guardar, enviar, importar, las solicitudes de permisos y cualquier acción que tarde en cargar.

Rutas de error

Un punto de control indica al lector cómo es el éxito. Una ruta de error indica cómo es el fallo y adónde ir después. Escribe una ruta para cada punto de control que pueda fallar. La ruta nombra el mensaje visible, la acción que debe tomar y el paso al que debe volver.

Considera un paso de carga. El punto de control de éxito dice "The file name appears in the list.". La ruta de error dice: "If the list shows Upload failed, select Try again. If it fails a second time, go to the troubleshooting page for file size limits." El lector ve el mensaje, conoce la acción y sabe cuándo parar.

Mantén las rutas de error cortas. Una ruta con tres ramas pertenece a una guía de solución de problemas aparte, enlazada desde el paso. Una ruta que necesita más de una pantalla para explicarse suele ser dos tareas.

Dónde deben ir los puntos de control en una guía larga

Una guía sin puntos de control falla tarde, después de que el lector haya hecho varios cambios que ahora necesita deshacer. Los números siguientes describen una guía de ejemplo de 12 pasos, con los puntos de control colocados donde la siguiente acción del lector depende de un resultado.

Un punto de control que indica un resultado visible es más útil que uno que dice "Done". "Done" no confirma nada en la pantalla. "The row shows Imported with 240 records" da al lector un número que puede comparar con su propia pantalla.

Escribe las ramas a partir de condiciones observables

Las ramas son el punto donde los lectores se pierden. Basalas en algo que el lector pueda ver, no en algo que deba saber.

• Débil: "If you are on the legacy plan, ..."
• Claro: "If the page shows Upgrade to continue, go to step 7."

Mantén las ramas cortas. Si una rama tiene más de dos pasos, trasládala a su propia guía y enlázala.

Evita las ramas que dependen del historial del lector. "If you signed up before 2025" pide al lector que recuerde algo que la pantalla no muestra. Sustitúyela por el resultado visible: "If the account page shows a Legacy badge, go to step 7." Una rama basada en la pantalla sirve para un lector nuevo, para uno que vuelve y para un agente de soporte que consulta la guía por otra persona.

Una rama que parte de una pantalla

El flujo siguiente muestra una rama que el lector puede comprobar en la pantalla. El lector no necesita saber qué plan tiene.

La rama devuelve al lector a un punto conocido. El paso 9 termina la guía para los lectores que no pueden exportar, así que los demás no tienen que saltarlo.

Deja que las capturas muestren ubicación y estado

El texto dice qué hacer. Una captura muestra dónde está y cómo se ve. Usa una por paso, recortada al área que importa, con una sola marca sobre el destino. Una captura también confirma el estado: el lector compara su pantalla y sabe que va bien.

Temposhot construye esa pareja a partir de tus clics. Abre Action Capture (Command+3), activa Parse clicked elements en Configure y selecciona Start Action Capture. Cada clic aceptado guarda la pantalla justo antes del clic, con un título provisional como Click "[[element-name]]". Después de Finish capture, el documento se abre en el editor.

Recorta cada captura a la ventana o al control que nombra el paso. Una pantalla completa muestra muchos controles, y el lector tiene que encontrar el que nombra el paso. Antes de exportar, comprueba que el recorte no muestre datos privados, como un nombre de cuenta o una notificación ajena, y revisa la imagen al tamaño en que se imprimirá o se mostrará.

Reescribe cada título provisional con las reglas anteriores, por ejemplo Click "Save" por "Select Save to keep the changes". Pon los puntos de control y las condiciones en la Page description. En una exportación a PDF, las descripciones pueden aparecer antes o después de cada captura (una personalización Pro). La guía del editor cubre títulos, descripciones y herramientas.

Ajustes para una guía práctica

Los ajustes siguientes producen una página por clic con un destino visible. Coinciden con una guía escrita para un lector que trabaja en una sola ventana.

Usa el atajo manual para una pantalla que cambia sin un clic, como un estado que se actualiza después de procesar algo. Activa Show cursor in shortcut captures para esos pasos, de modo que el puntero marque el campo que el lector debe leer.

Mantén el mismo destino de captura en toda la guía. Un cambio de Active Window a Specific Window a mitad de guía hace que el encuadre de las páginas sea incoherente.

Teclas del editor para redactar páginas de pasos

La mayoría de las ediciones se hacen en el editor, una página cada vez. Las teclas siguientes cubren las acciones que más se usan al redactar títulos, descripciones y marcas.

Elimina el relleno y las suposiciones ocultas

Elimina las palabras que no cambian lo que hace el lector:

• "Simply", "just", "easily": no aportan nada y hacen sentir peor a los lectores que tienen dificultades.
• "You will now want to", "Go ahead and": empieza por el verbo.
• "As mentioned above": repite el dato o enlázalo.

Después busca las suposiciones. ¿El lector sabe dónde está la app, qué cuenta usar, qué significa un término? Añade una línea para cada hueco, normalmente en los requisitos previos.

Mide el recorte

El relleno es fácil de añadir y fácil de pasar por alto. Contar las palabras antes y después de una edición muestra cuánto elimina una sola revisión.

El recorte hace más que acortar la página. Cada frase eliminada era un lugar donde el lector se detenía a decidir si importaba. El paso editado se lee como una instrucción en la primera lectura.

Prueba las instrucciones sin explicarlas

Da las instrucciones a alguien que no ha hecho la tarea. Obsérvalo mientras las sigue, y no respondas preguntas. Cada pausa o pregunta señala un paso que necesita una acción, una etiqueta o un punto de control más claros.

Elige personas que se parezcan a los lectores. Quien construyó el producto conoce las etiquetas y el flujo, así que su ejecución limpia demuestra poco. Una persona del equipo de soporte o alguien nuevo en el rol de destino encuentra los huecos que el autor ya no ve. Dale a la persona la guía y la cuenta que usará, y nada más.

Corrige esos pasos y vuelve a probar con otra persona si puedes. Dos ejecuciones limpias son una buena señal de que las instrucciones funcionan. La lista de comprobación para tutoriales de capturas enumera las comprobaciones que quedan antes de publicar.

Ejecuta una sesión con notas

Anota la hora y el número de paso de cada pausa, y deja la explicación para después de la sesión. El cronograma siguiente muestra una sesión sobre una guía de nueve pasos con un hallazgo útil.

Las notas muestran qué pasos necesitan etiquetas y cuáles un punto de control. Una sola sesión muestra un patrón, no una tasa, así que haz una segunda sesión antes de cambiar la guía otra vez.

Archivos que se guardan con una guía práctica

Una guía tiene más archivos que páginas. El documento de origen permanece en la biblioteca de Documents, y el PDF exportado y las notas van en una carpeta fuera de la app. La carpeta conserva el número de versión y las notas de la prueba junto al archivo que reciben los lectores, así que la siguiente edición parte del mismo registro.

Preguntas frecuentes

¿Debo usar "click" o "select" en las instrucciones?

"Select" funciona para ratón, teclado y tacto. Usa "click" solo si tu público usa ratón y tu guía de estilo lo prefiere. Elijas lo que elijas, úsalo de forma coherente.

¿Cuánto debe ocupar un paso?

Una frase para la acción, más una frase opcional para el resultado o la condición. Las explicaciones más largas van en una nota o en una página aparte.

¿Las instrucciones necesitan pasos numerados?

Sí, cuando el orden importa. Los números permiten al lector no perder su lugar y permiten a soporte referirse al "paso 4". La exportación a PDF de Temposhot puede añadir números de paso (Pro).

¿Dónde van las advertencias?

Antes del paso al que se aplican. Una advertencia después de una acción destructiva llega demasiado tarde.

¿Cuántas capturas necesita una guía?

Una por cada paso en el que cambia la pantalla o en el que el destino es difícil de encontrar. Un paso que solo escribe texto en un campo ya visible no necesita una. Cuenta las capturas frente a los pasos después del primer borrador, y elimina las que repitan la misma pantalla.

¿Qué pasa si la interfaz cambia después de publicar?

Localiza cada paso que nombre una etiqueta o una ubicación cambiada, y actualiza la captura y el título a la vez. Una captura nueva con una etiqueta antigua confunde más al lector que la captura antigua. Registra la versión de la app en la descripción de la página o en el pie de la guía, para que los lectores sepan a qué versión se refiere.

¿Cómo escribo para lectores que solo usan el teclado?

Nombra la tecla o el destino del foco cuando el paso dependa de ello, como "Press Tab until the Export button has focus". No confíes en la palabra "click" ni en la posición de un control en la pantalla, porque un lector de teclado no ve la posición de la misma manera. Prueba una ejecución solo con el teclado antes de publicar.

¿Cuántos puntos de control son suficientes?

Uno después de cada acción que guarda, envía, importa o cambia un acceso, y uno después de cualquier paso que tarde más de unos segundos. Demasiados puntos de control ralentizan al lector, así que combina los que corresponden a dos acciones que siempre ocurren juntas.

Convierte tus clics en una guía paso a paso clara

Action Capture te da una captura y un título provisional por clic, listos para estas reglas de redacción. Descarga Temposhot y escribe tu próxima guía sobre una grabación.