Cómo escribir documentación técnica

Elige una tarea, un lector y una única fuente de verdad. Luego escribe los pasos en un lenguaje claro, pruébalos con alguien que no los haya escrito y elimina todo lo que no ayude al lector a terminar el trabajo.

Antes de escribir

Una buena documentación técnica empieza antes de la primera frase. Primero elige una tarea. Por ejemplo, escribe sobre «conectar una nueva pasarela de pago», no sobre «documentar la app». Así tienes un final claro y la página sigue siendo útil.

Después, define al lector. Un desarrollador necesita notas de instalación, comandos y casos extremos. Un agente de soporte necesita síntomas, comprobaciones y soluciones. Un responsable de proyecto puede necesitar estado, dependencias y notas de traspaso. Una sola página puede servir bien a uno de ellos, o fallarle a los tres.

Luego reúne la fuente de verdad. Puede ser código, tickets, capturas de pantalla, notas de diseño, registros, un runbook o un manual antiguo que aún tenga una buena sección. Si dos fuentes no coinciden, para y pregunta cuál manda antes de redactar.

Elige el formato antes de empezar a escribir. Una guía de instalación, una página de referencia y una página de solución de problemas necesitan formas distintas. Para un controlador de mesa elevable, una guía de instalación podría explicar el emparejamiento y la calibración. Una página de referencia podría listar los nombres de los botones y el significado de las luces. Una página de solución de problemas podría cubrir un elevador atascado o una luz de error parpadeante.

Cómo escribir documentación técnica

• Escribe primero el resultado. Di qué podrá hacer el lector al terminar la página. Ejemplo: «Al final, tendrás la app de staging conectada a Stripe».
• Usa un flujo simple: propósito, lo que necesitas, pasos, resultado, soluciones. Así el lector avanza sin pararse.
• Escribe una acción por paso. «Abre la consola de administración. Selecciona Facturación. Elige Añadir método de pago». Es más fácil de seguir que un párrafo largo con cinco verbos.
• Usa nombres exactos para botones, campos, carpetas, comandos, códigos de error y nombres de archivo. Si en la pantalla pone Añadir método de pago, no lo cambies por Tarjeta nueva en la documentación.
• Mantén los términos estables. Si dices workspace en el paso 1, no cambies a área del proyecto en el paso 4.
• Pon el problema más probable junto al paso que lo provoca. Si el acceso suele ser el problema, dilo ahí. Ejemplo: «Si falta el botón, comprueba que tienes acceso de Billing Admin».
• Usa ejemplos que se puedan copiar para software y código. Muestra el comando y justo después el resultado esperado. Así el lector puede comprobar rápido su propia pantalla.
• Escribe párrafos cortos. Un solo idea por párrafo basta. Si un párrafo tiene demasiadas ideas, sepáralo en dos.
• Recorta todo lo que no ayude a alguien a terminar la tarea. El contexto solo sirve si evita un error.
• Añade el siguiente paso al final. Por ejemplo, enlaza la página de prueba, la página de solución de problemas o la parte de instalación que viene después.

Una plantilla simple para los pasos

Un formato estable para los pasos mantiene la documentación legible cuando la tarea se complica. Usa esta estructura para cada paso: acción, resultado, solución si hace falta. Funciona para la instalación de software, los traspasos de proyectos y los flujos de trabajo basados en comandos.

Ejemplo para una página de desarrollador: «Ejecuta npm install. Deberías ver cómo se actualiza la lista de paquetes. Si falla, comprueba que Node 20 esté instalado». Eso le da al lector algo que hacer, algo que esperar y algo que comprobar.

Antes: «Luego gestiona el problema de la dependencia». Después: «Ejecuta npm install. Si ves un error de permisos, vuelve a abrir la terminal con un usuario que tenga acceso de escritura». La segunda versión cuesta más de escribir y menos de usar.

Para una página de controlador de mesa, podrías escribir: «Mantén pulsados los botones de subir y bajar durante tres segundos. La pantalla debería parpadear una vez. Si no lo hace, desconecta el controlador y vuelve a intentarlo». Es claro, comprobable y específico.

Qué incluye una buena documentación técnica

Una página útil suele seguir este orden: título, apertura breve, requisitos previos, pasos, resultados esperados, soluciones, siguiente paso. Ese orden funciona porque responde a las preguntas del lector en el mismo orden en que aparecen.

El título debe nombrar la tarea. La apertura debe decirle al lector para quién es la página y qué cubre. Los requisitos previos deben listar solo lo que bloquea el avance, como una cuenta, un cable, una versión o un inicio de sesión.

Los pasos deben ir en el orden real, no en el que parece más ingenioso. Pon las advertencias solo donde importan. Añade una sección breve de solución para los fallos más comunes. Termina con un punto de cierre claro, como una prueba o un traspaso.

Para una página de configuración de una pasarela de pago, podría ser así: «Conecta Stripe a la app de staging. Necesitas acceso de administrador y una clave de prueba. Sigue los pasos para pegar la clave, guardar la configuración y hacer un cargo de prueba. Si la prueba falla, comprueba la clave y los permisos de la cuenta. Luego pasa a la página de configuración del webhook».

Pruébalo antes de publicarlo

No te fíes del borrador solo porque a ti te parezca claro. Dáselo a alguien que no lo haya escrito. Pídele que lo siga sin ayuda. Observa dónde se detiene, duda o retrocede.

Si se detiene, puede faltar un requisito previo o un pequeño paso de preparación. Añade ese paso cerca del primer punto en que lo necesite.

Si duda, el texto es confuso. Sustituye «introduce el valor correcto» por el nombre exacto del campo, la etiqueta o la ruta del archivo.

Si retrocede, el orden está mal. Mueve el paso antes o divide la página para que el lector no tenga que ir saltando de un lado a otro.

Intenta corregir la parte confusa, no solo la frase que la rodea. A veces la solución real es un nuevo requisito previo, cambiar una captura de pantalla o crear una segunda página.

Para una comprobación rápida, recorre tools manual check. Si necesitas el mismo hábito para instrucciones físicas, compara la estructura con this guide.

Qué suele salir mal

El problema más común es demasiado contexto y muy poca acción. El lector no necesita una lección de historia antes del nombre del botón.

Otro fallo es mezclar tareas en una sola página. La configuración, la solución de problemas y la referencia compiten por el espacio. Sepáralas cuando el lector tenga que cambiar de modo mental.

Las capturas de pantalla envejecen rápido. Úsalas solo en pantallas que cambian poco. Cuando las etiquetas se mueven mucho, usa una breve llamada o una imagen recortada en lugar de una captura a pantalla completa.

Las palabras vagas también causan problemas. Evita «simplemente», «fácilmente» y «solo». No arreglan un despliegue atascado ni una autorización que falta.

Cuando una página parece recargada, quita primero lo sobrante. Quédate con los pasos que llevan al lector a un resultado que funciona.

Cuánto tarda

Una página breve de cómo hacerlo puede llevar de 30 a 60 minutos si la fuente está limpia y la tarea es sencilla.

Una guía normal de configuración de software suele llevar de 2 a 4 horas, contando el borrador, la revisión de los pasos y la edición.

Una página de proyecto más grande, con casos límite, capturas de pantalla y rondas de revisión, puede llevar gran parte de un día.

La parte lenta suele ser demostrar que los pasos funcionan, no escribirlos. Si el proceso es enrevesado, escribe la documentación mientras haces la tarea. Así detectas rápido clics que faltan, supuestos ocultos y frases torpes.

Cuándo ayuda una versión en vídeo

Una página escrita sigue siendo el mejor sitio para buscar, consultar y copiar texto exacto. Un vídeo ayuda cuando la tarea tiene muchos pasos, pantallas que cambian o preguntas repetidas de soporte. Esto es muy común en onboarding, configuración y procedimientos prácticos.

Si ya tienes un manual o una página de instrucciones, una versión breve en vídeo puede ir junto a ella. Manual to Video convierte un manual existente en una película animada y subtitulada, paso a paso, con los colores y el logo de tu marca. También puede funcionar con un código QR en el manual, la caja, la página de producto o un artículo de soporte.