Cómo planificar un conjunto de documentación de software basado en capturas

Un conjunto de documentación con capturas es fácil de empezar y difícil de mantener. Cada imagen es una copia de la interfaz de un día concreto, y la interfaz sigue cambiando. Planificar antes de capturar decide si el conjunto sobrevive a su primer rediseño.

Esta publicación explica cómo estructurar el conjunto, cómo fijar reglas para las capturas y cómo producirlas en un Mac con Temposhot. Un ejemplo práctico recorre cada sección: una pequeña aplicación web de facturación con cinco áreas de producto y una redactora técnica que también atiende soporte.

Enumera las preguntas que los lectores necesitan resolver

Reúne preguntas reales antes de decidir las páginas. Buenas fuentes son los tickets de soporte, las llamadas de ventas, las sesiones de incorporación, los hilos del chat interno y los términos de búsqueda de la documentación actual.

Escribe cada pregunta con las palabras del lector:

• "¿Cómo invito a un compañero de equipo?"
• "¿Por qué mi exportación aparece en blanco?"
• "¿Qué significa el estado de sincronización?"
• "¿Qué plan incluye los registros de auditoría?"

Agrupa los duplicados. La lista resultante es el alcance del conjunto. Lo que no esté en ella puede esperar.

Ejemplo práctico: de los tickets a la lista de preguntas

El equipo de facturación exportó 240 tickets de soporte de los últimos 90 días. Leer solo las líneas de asunto y el primer mensaje del cliente llevó unas dos horas. Tras fusionar los duplicados, quedaron 52 preguntas distintas.

Nueve preguntas aparecieron más de diez veces cada una. Esas nueve cubrían casi la mitad de todos los tickets, así que fijaron el orden del trabajo. Las otras 43 preguntas pasaron a un pendiente ordenado por área: facturas, clientes, pagos, ajustes y facturación.

Registra las palabras que usan los lectores

Mantén la redacción del lector junto a cada pregunta, aunque no coincida con la etiqueta de la interfaz. Un cliente que escribe "quitar una tarjeta" no buscará "Métodos de pago". El título de la página debe usar la etiqueta del producto, y la primera frase puede repetir el término del lector para que la búsqueda encuentre ambos.

Anota también el contexto de cada pregunta: el plan, el rol y el dispositivo. "¿Cómo reembolso una factura?" de un titular de cuenta y la misma pregunta de un rol de solo lectura llevan a páginas distintas. Una es una guía de tarea y la otra es una página de resolución de problemas sobre permisos que faltan.

Quita las preguntas que la documentación no puede resolver

Algunos tickets describen un error o una función que falta. Una página que explica un error se convierte en un workaround que sobrevive a la corrección. En el ejemplo, 6 informes de error se apartaron durante la fusión, antes del recuento de 52, y pasaron al equipo de producto en lugar del pendiente de documentación.

Otras preguntas nacen de una etiqueta confusa. Si diez lectores preguntan qué significa "Sync", una página de referencia ayuda, pero una etiqueta más clara ayuda más. Envía también esas preguntas al equipo de producto, y escribe la página solo si la etiqueta se mantiene.

Asigna un tipo de página a cada pregunta

Cada pregunta necesita una forma de página distinta. Mezclarlas hace que las páginas sean largas y difíciles de recorrer.

Tipo de página	Responde	Capturas
Guía de tarea	"Cómo hago X"	Una por paso
Referencia	"Qué significa X"	Una vista general anotada por pantalla
Resolución de problemas	"Por qué falló X"	El estado de error y la solución
Concepto	"Cómo funciona X"	Diagramas, pocas capturas o ninguna

Etiqueta cada pregunta de la lista con un tipo. La mayoría de las preguntas de producto acaban como guías de tarea.

Cuenta las capturas antes de escribir

El tipo de página predice cuántas imágenes llevará cada página. Multiplícalo por el número de páginas, y el resultado es el número de imágenes que hay que actualizar después de cada rediseño. Conviene conocer esa cifra antes de que alguien abra una herramienta de captura.

En el ejemplo, 31 de las 52 preguntas se convirtieron en guías de tarea, con una media de 7 pasos. Doce se convirtieron en páginas de resolución de problemas con 2 imágenes cada una, 6 en páginas de referencia con 1 vista general anotada cada una, y 3 en páginas de concepto sin capturas.

Las 247 imágenes son la carga real de mantenimiento del conjunto. Un rediseño de un área de producto que afecte a una quinta parte de ellas supone unas 50 sustituciones, lo que equivale a uno o dos días de trabajo. Conocer ese número facilita defender la política de capturas que aparece más abajo.

Divide las preguntas que mezclan tipos

Algunas preguntas combinan dos tipos a la vez. "¿Por qué mi exportación está en blanco y cómo lo soluciono?" es una página de resolución de problemas que enlaza a una guía de tarea. Escribe la página de resolución con el error y la causa, y enlaza a la guía de tarea para el procedimiento completo.

Define una política de capturas

Decide una vez cómo deben verse las capturas, y escríbelo. Un conjunto coherente parece mantenido y es más rápido de actualizar.

• Tamaño de ventana: un tamaño fijo para todas las capturas. El destino Specific Window de Action Capture de Temposhot mantiene la misma ventana durante toda una ejecución.
• Tema e idioma: claro u oscuro, y un solo idioma de interfaz.
• Datos: solo cuentas de muestra y nombres de prueba.
• Recorte: la ventana o el panel, nunca el escritorio completo. Usa Framing con Focus on action en Balanced o Close.
• Marcas: un marcador de clic o una flecha por imagen, y un solo color de acento.
• Formato: PNG para el texto de la interfaz, WebP si tu sitio necesita archivos más pequeños.

Decide también dónde no hacen falta capturas: un ajuste de un solo campo, un paso cuya etiqueta ya está en el texto, una pantalla que cambia en cada versión.

Traduce la política a ajustes de captura

Una política escrita solo sirve si los ajustes de captura la respetan. Configura Action Capture una vez y los valores quedan guardados en el Mac para todas las ejecuciones posteriores. El equipo del ejemplo usó los ajustes siguientes en las 31 guías de tarea.

Specific Window mantiene una sola ventana del navegador como destino durante toda la ejecución, así que cada paso tiene el mismo ancho en píxeles. Desactiva Include toolbar in captures, o la barra flotante aparecerá en las imágenes de la documentación. Mantén Capture outside clicks desactivado salvo que la tarea use una segunda ventana, como un gestor de contraseñas.

Define niveles de encuadre por tipo de página

El encuadre no cambia la imagen original, así que la política puede fijar un nivel y aun así permitir excepciones. Las guías de tarea usaron Balanced (nivel 3) por defecto, que conserva suficiente página para que el lector encuentre el control. Los controles pequeños, como un interruptor en una lista larga de ajustes, pasaron a Close (nivel 4).

Las vistas generales de referencia no usaron encuadre. Muestran la ventana completa con etiquetas numeradas, porque la idea es nombrar cada región. Step Numbers es una herramienta de Pro, así que en el plan gratuito el mismo resultado necesita etiquetas Text colocadas a mano.

Decide cuándo no capturar

Cada imagen es una actualización futura, así que la política también debe enumerar los casos sin captura. El equipo del ejemplo omitió las imágenes de los pasos en los que la única acción era escribir un valor en un campo con etiqueta. También omitió los mensajes de confirmación que desaparecen en 3 segundos, y describió el mensaje en texto.

Si ninguno de los cinco puntos aplica, escribe el paso solo como texto. En el ejemplo, esta regla eliminó 38 de las 217 imágenes previstas para las guías de tarea antes de empezar la captura.

Prepara una cuenta de muestra para cada captura

Las capturas de cuentas distintas muestran nombres, totales y fechas diferentes, y los lectores lo notan. El equipo del ejemplo creó un espacio de trabajo de muestra con 3 clientes, 12 facturas y 2 métodos de pago, todos con nombres de prueba. Cada guía parte de ese espacio de trabajo, así que el mismo nombre de cliente aparece en todas las páginas.

Restablece los datos de muestra antes de cada ejecución. Una guía grabada después de que otra guía haya eliminado una factura mostrará 11 facturas en lugar de 12, y la siguiente actualización no coincidirá. Escribe los pasos de restablecimiento al principio del documento de política, para que otra persona redactora pueda repetirlos.

Define el tamaño de la ventana del navegador antes de cada ejecución y no lo cambies. Temposhot captura la ventana con su tamaño actual; no cambia el tamaño de las ventanas. Una nota en la política como "ventana del navegador de 1440 puntos de ancho, zoom al 100 por ciento" mantiene las capturas de días distintos a la misma escala.

Nombra y almacena las imágenes para poder reemplazarlas

Cada imagen se reemplazará en algún momento. Nombra los archivos para encontrar rápidamente todas las imágenes de una misma pantalla.

Un patrón como area-tarea-paso.png, por ejemplo billing-change-plan-03.png, ordena por área y por tarea. Mantén una carpeta por guía, y guarda el Document de Temposhot de cada guía para poder exportar de nuevo después de las ediciones.

Las exportaciones de imagen de Temposhot usan los títulos de página en los nombres de archivo. Define los títulos antes de exportar, o renombra los archivos en el repositorio de documentación después. El paquete ZIP añade document.json junto a las páginas PNG renderizadas, lo que ayuda si automatizas importaciones en un sistema de documentación.

Estructura de carpetas para el conjunto del ejemplo

Una carpeta por área de producto contiene una carpeta por guía. Las imágenes exportadas se colocan junto a la página que las usa, así que una solicitud de cambios que modifica una guía también muestra qué imágenes cambiaron.

Mantén sincronizados los títulos de página y los nombres de archivo

Como Temposhot nombra los archivos de imagen con los títulos de página, un título como Click "Change plan" produce un nombre de archivo difícil de ordenar. Hay dos rutas viables. Reescribe los títulos de página con el texto final dirigido al lector y renombra los archivos del repositorio con un script, o exporta un paquete ZIP y usa el orden de páginas de document.json para nombrar los archivos.

Sea cual sea la ruta que elija el equipo, el número de paso del nombre de archivo debe coincidir con el número de paso de la página. Cuando se elimine el paso 4, renumera en el mismo commit los archivos que le siguen.

Guarda los Documents de origen

Cada imagen exportada procede de un Document del Mac que la grabó. Los Documents viven en la biblioteca de Documents (Command+4) de ese Mac, y Temposhot no los sincroniza. Nombra cada Document exactamente como la carpeta de su guía, por ejemplo billing-change-plan, para poder localizar el origen de cualquier imagen buscando en la biblioteca.

Crea las guías de tarea antes que los recorridos generales

Las guías de tarea responden a las preguntas más comunes y son las más fáciles de verificar. Escríbelas primero.

1. Abre Action Capture

   Pulsa Command+3, selecciona Start Action Capture y elige Specific Window.

2. Realiza la tarea

   Haz clic en la tarea una vez. Cada clic aceptado guarda la ventana justo antes del clic, con un título de borrador de Parse clicked elements.

3. Termina y edita

   Selecciona Finish capture. En el editor, reescribe los títulos, encuadra las páginas y añade las marcas.

4. Exporta las páginas

   Abre More export formats y elige páginas PNG o WebP para el sitio de documentación.

Los recorridos de producto y las páginas de visión general llegan después, cuando las guías de tarea muestran qué pantallas importan más. La guía de Action Capture y la guía de exportación de Documents explican los detalles.

Ordena el primer lote por volumen de tickets

El equipo del ejemplo capturó las nueve preguntas más planteadas durante la primera semana. Cada guía llevó unos 25 minutos: 5 minutos para restablecer la cuenta de muestra, 5 para grabar y 15 para editar títulos, encuadres y marcas. Las nueve guías llevaron aproximadamente cuatro horas en total.

Reescribe los títulos de borrador como instrucciones

Parse clicked elements completa cada título de página con el nombre del control, por ejemplo Click "Change plan". Los clics en controles sin un nombre legible reciben Click here. Ambos son borradores. Un título para el lector empieza con un verbo, nombra el control en negrita y añade el resultado cuando no es evidente.

Título de borrador	Título reescrito
Click "Billing"	Abre Billing en la barra lateral
Click here	Selecciona la tarjeta del plan Team
Click "Confirm"	Selecciona Confirm para cambiar de plan en la próxima renovación

El título reescrito también se convierte en el nombre del archivo de imagen al exportar, así que un título claro ayuda tanto a los lectores como al repositorio.

Comprueba el número de pasos frente al límite gratuito

El plan gratuito pausa una ejecución de Action Capture después de 5 pasos, y los pasos ya capturados se conservan. Las guías de siete pasos como las del ejemplo necesitan Temposhot Pro, o dos ejecuciones añadidas a un mismo Document. Añadir una segunda ejecución se hace con Capture new images… en el panel Pages, que añade los fotogramas nuevos al Document abierto.

Edita las páginas con atajos de teclado

La edición es donde se va la mayor parte de los 25 minutos por guía. Las teclas del editor siguientes cubren las ediciones comunes en páginas de documentación.

Las anotaciones no son destructivas. Un rectángulo añadido en esta versión se puede mover o eliminar después del siguiente rediseño sin volver a capturar el paso, siempre que la pantalla de fondo siga coincidiendo.

Conecta el conjunto de documentación

Los lectores rara vez llegan a la página que necesitan. Enlaza las páginas para que puedan pasar de un concepto a la tarea, y de un error a la solución.

• Cada guía de tarea enlaza a sus requisitos previos y a la siguiente tarea más probable.
• Cada página de resolución de problemas enlaza a la guía de tarea que la corrige.
• Cada página de referencia enlaza a las tareas que usan la pantalla.

Una página índice breve por área de producto, con las tareas agrupadas por objetivo, ayuda a los lectores que navegan en lugar de buscar.

Patrón de enlaces desde una pregunta

La pregunta "¿Por qué mi exportación aparece en blanco?" del ejemplo generó una cadena de cuatro páginas. Un lector que llegue a cualquiera de ellas puede alcanzar las otras tres con un solo clic.

Evita páginas huérfanas

Después de publicar, enumera todas las páginas y cuenta los enlaces entrantes. Una página sin enlaces entrantes solo se encuentra con la búsqueda. En el ejemplo, 4 de las 52 páginas no tenían ninguno, y cada una se añadió a su índice de área.

Asigna responsabilidades y desencadenantes de revisión

Asigna un responsable a cada página, normalmente el equipo dueño de la función. Registra la versión del producto a la que corresponden las capturas.

Los desencadenantes de revisión funcionan mejor que los recordatorios de calendario por sí solos:

• Una versión cambia una pantalla que aparece en el conjunto.
• Se renombra una etiqueta o un elemento de menú.
• Soporte informa de un paso que ya no coincide.
• Pasa un intervalo fijo, por ejemplo un trimestre, sin ningún otro desencadenante.

La publicación sobre cómo mantener actualizada la documentación con capturas explica la rutina de actualización.

Sustituye las imágenes después de una versión

Cuando una versión cambia una pantalla, los nombres de archivo permiten encontrar fácilmente las imágenes afectadas. Busca en el repositorio el prefijo del área, abre los Documents correspondientes y vuelve a ejecutar solo los pasos que cambiaron.

Las páginas nuevas de una captura se pueden insertar después de la página seleccionada. Selecciona la página anterior al paso cambiado, ejecuta la captura, y la página nueva quedará en la posición correcta.

Reparte la responsabilidad por área de producto

Una sola persona redactora no puede revisar 52 páginas después de cada versión. El equipo del ejemplo asignó cada área a la persona ingeniera que la mantiene, con la redactora como editora. La responsable marca las pantallas cambiadas en el ticket de la versión, y la redactora sustituye las imágenes.

Registra la versión del producto en cada página

Añade la versión del producto a los metadatos de la página o a la última línea, por ejemplo "Las capturas corresponden a la versión 4.2". Cuando soporte informe una discrepancia, la versión indica al responsable cuánto se ha quedado atrás la página. Las páginas con más de dos versiones de retraso pasan al principio de la cola de revisión.

Preguntas frecuentes

¿Cuántas capturas debe tener una página de documentación de software?

Una por paso en las guías de tarea, y las mínimas posibles en el resto. Cada imagen es una actualización futura, así que añade una solo cuando ahorre esfuerzo al lector.

¿Las capturas de la documentación deben mostrar la pantalla completa?

Rara vez. Recorta a la ventana o al panel. Las imágenes de pantalla completa muestran apps no relacionadas y reducen el texto de la interfaz.

¿Qué es la documentación visual?

Documentación que combina capturas, diagramas o vídeo con texto. Consulta documentación visual en el glosario.

¿Qué formato de imagen debe usar un sitio de documentación?

Las páginas PNG mantienen nítido el texto de la interfaz. Las páginas WebP generan archivos más pequeños y aparecen en More export formats solo cuando hay un codificador WebP disponible en el Mac. El Image Compressor puede reducir aún más los archivos PNG antes de subirlos.

¿Cuánto tarda una actualización de capturas después de un rediseño?

Depende de cuántas imágenes muestren las pantallas cambiadas. En el ejemplo, el rediseño de un área afectó a unas 50 de las 247 imágenes. Volver a ejecutar solo los pasos cambiados desde los Documents guardados tardó entre uno y dos días, frente a casi una semana para reconstruir las mismas guías desde cero.

¿Pueden varias personas redactoras compartir un mismo Document de Temposhot?

No. Los Documents se guardan en el Mac que los creó. Comparte los archivos exportados a través del repositorio de documentación, y mantén cada Document de origen en el Mac de su responsable.

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

Action Capture graba cada guía de tarea en una sola pasada, con un tamaño de ventana uniforme y títulos de borrador. Descarga Temposhot y empieza por la pregunta más solicitada de tu lista.