Artículos etiquetados: Redacción
La accesibilidad en la documentación no termina con la navegación y el contraste. Los ejemplos de código, las respuestas JSON y las tablas de referencia también deben seguir siendo comprensibles y útiles sin depender solo del color.
Una petición técnicamente válida no es necesariamente un buen ejemplo. Usa valores realistas y secuencias que revelen el modelo de la API y permitan al developer anticipar el siguiente paso. Un ejemplo obtenido de un schema puede ser sintácticamente correcto y no enseñar nada.
Una guía práctica y verificable sobre Documentación de autenticación que evita tickets de soporte, pensada para equipos que necesitan mantener la documentación clara y sostenible. Cómo abordar «Documentación de autenticación que evita tickets de soporte» con criterios prácticos, verificables y mantenibles para documentación técnica.
Una lista útil ya no es una colección de clásicos. Compara las guías activas de Microsoft, Google, GitHub e IBM, usa Diátaxis para revisar la estructura y convierte cada lectura en un ejercicio concreto.
Leer sobre documentación ayuda, pero la habilidad crece más rápido al repetir ejercicios pequeños de investigación, reestructuración, edición y verificación con feedback claro. “Mejorar en technical writing” es demasiado amplio.
Una guía práctica y verificable sobre Diagramas como código: cuándo ayudan y cuándo no, pensada para equipos que necesitan mantener la documentación clara y sostenible. Cómo abordar «Diagramas como código: cuándo ayudan y cuándo no» con criterios prácticos, verificables y mantenibles para documentación técnica.
Una guía práctica y verificable sobre Documentar errores de API para que el desarrollador pueda recuperarse, pensada para equipos que necesitan mantener la documentación clara y sostenible. Cómo abordar «Documentar errores de API para que el desarrollador pueda recuperarse» con criterios prácticos, verificables y mantenibles para documentación técnica.
Una buena documentación de API combina contratos legibles por máquina con explicaciones humanas, ejemplos ejecutables y errores explícitos. La documentación REST tiene dos audiencias: máquinas y personas.
Una guía práctica y verificable sobre Ejercicios de edición que mejoran la escritura técnica, pensada para equipos que necesitan mantener la documentación clara y sostenible. Cómo abordar «Ejercicios de edición que mejoran la escritura técnica» con criterios prácticos, verificables y mantenibles para documentación técnica.
Una guía práctica y verificable sobre Markdown a escala: convenciones que evitan el caos, pensada para equipos que necesitan mantener la documentación clara y sostenible. Cómo abordar «Markdown a escala: convenciones que evitan el caos» con criterios prácticos, verificables y mantenibles para documentación técnica.
Una descripción OpenAPI puede generar una referencia precisa, pero los developers siguen necesitando conceptos, flujos, autenticación, ejemplos y recuperación de errores que un schema no puede explicar por sí solo. OpenAPI describe muy bien operaciones, parámetros, estructuras de request y response, status codes y schemas reutilizables.
Una guía práctica y verificable sobre Notas de versión sobre las que el usuario puede actuar, pensada para equipos que necesitan mantener la documentación clara y sostenible. Cómo abordar «Notas de versión sobre las que el usuario puede actuar» con criterios prácticos, verificables y mantenibles para documentación técnica.