Acerca del servicio
TraducidoEscribo documentación técnica y ayuda de productos que la gente realmente lee: una guía del usuario, un centro de ayuda, una referencia de API. El trabajo comienza desarmando el producto. Lo reviso como lo haría un recién llegado, anoto cada lugar donde me quedé atascado y recojo las tareas reales con las que llegan tus usuarios. La estructura surge de esas tareas, no de tu árbol de menú: primero el lanzamiento y la primera pequeña victoria, luego el trabajo diario, y solo después los escenarios complejos que pocas personas necesitan pero que consumen la mayor parte del tiempo del equipo de soporte.
Cada artículo es un conjunto de pasos con capturas de pantalla, subtituladas para que el lector nunca tenga que adivinar qué botón se refiere. Una sección separada cubre errores comunes y qué hacer al respecto: el texto en la pantalla, la razón detrás de él, la salida. La parte de la API incluye ejemplos de solicitudes y respuestas para cada método, explica campos y códigos de estado, y dice claramente qué se devuelve en caso de fallo. Un glosario mantiene los términos del producto en un solo lugar, de modo que la interfaz, la ayuda y las respuestas de soporte utilicen las mismas palabras, y una breve guía de estilo fija el tono y la redacción, para que el texto mantenga una sola voz incluso cuando otras personas lo añadan más tarde.
Cada instrucción se verifica al recorrer los pasos en el producto en vivo; nada escrito de la memoria de un desarrollador, sin esa revisión, entra en la ayuda. Claves, tokens y credenciales de prueba en ejemplos se reemplazan con marcadores de posición. La documentación para una función no terminada se marca como un borrador y nunca se presenta como lista.
— recorrido del producto y una lista de las tareas reales del usuario
— estructura de ayuda desde el primer lanzamiento hasta escenarios avanzados
— instrucciones paso a paso con capturas de pantalla y subtítulos
— una sección sobre errores comunes y qué hacer al respecto
— referencia de API con ejemplos de solicitudes y respuestas
— glosario de términos más una breve guía de estilo y tono
— cada instrucción verificada nuevamente en el producto en vivo
— fuentes entregadas en un formato que es fácil de editar más adelante
Cada artículo es un conjunto de pasos con capturas de pantalla, subtituladas para que el lector nunca tenga que adivinar qué botón se refiere. Una sección separada cubre errores comunes y qué hacer al respecto: el texto en la pantalla, la razón detrás de él, la salida. La parte de la API incluye ejemplos de solicitudes y respuestas para cada método, explica campos y códigos de estado, y dice claramente qué se devuelve en caso de fallo. Un glosario mantiene los términos del producto en un solo lugar, de modo que la interfaz, la ayuda y las respuestas de soporte utilicen las mismas palabras, y una breve guía de estilo fija el tono y la redacción, para que el texto mantenga una sola voz incluso cuando otras personas lo añadan más tarde.
Cada instrucción se verifica al recorrer los pasos en el producto en vivo; nada escrito de la memoria de un desarrollador, sin esa revisión, entra en la ayuda. Claves, tokens y credenciales de prueba en ejemplos se reemplazan con marcadores de posición. La documentación para una función no terminada se marca como un borrador y nunca se presenta como lista.
— recorrido del producto y una lista de las tareas reales del usuario
— estructura de ayuda desde el primer lanzamiento hasta escenarios avanzados
— instrucciones paso a paso con capturas de pantalla y subtítulos
— una sección sobre errores comunes y qué hacer al respecto
— referencia de API con ejemplos de solicitudes y respuestas
— glosario de términos más una breve guía de estilo y tono
— cada instrucción verificada nuevamente en el producto en vivo
— fuentes entregadas en un formato que es fácil de editar más adelante
