Redacción técnica
Compartir:
Estas preguntas solo se han mostrado a los encuestados que se dedican a la redacción técnica.
El 12 % de los encuestados afirmó dedicarse a la redacción técnica. Entre ellos, solo el 10 % ocupa un puesto oficial como redactores técnicos.
Esto significa que en el informe sobre el estado del ecosistema de los desarrolladores 2023 de JetBrains, el 90 % de los que redactan documentación no se autodenomina redactores técnicos, lo que plantea interrogantes sobre la colaboración entre equipos, la calidad y coherencia de la documentación y el papel de los redactores técnicos.
Daniele Procida
Director de ingeniería, Canonical
La documentación no es solo redacción técnica, o aquello que se escribe. Da forma a la relación de un usuario con un producto. También afecta a cómo lo entienden sus creadores: todos los implicados en un producto deben participar en la reflexión sobre este.
Alyssa Rock
Community Manager, The Good Docs Project
Una cosa queda clara: los desarrolladores ven el valor de una buena documentación (sobre todo porque saben lo incómodo y difícil que puede ser utilizar una herramienta que tiene una documentación deficiente). Solo que a veces no saben cómo hacer que su documentación sea buena.
Chris Chinchilla
Escritor y podcaster, chrischinchilla.com
Entre nuestra comunidad de redactores mantenemos interminables debates sobre lenguajes, herramientas y prácticas. Sin embargo, estas cifras demuestran que necesitamos herramientas, formación y asesoramiento a la comunidad que faciliten a todos y cada uno la redacción de documentación de calidad.
La mayoría de los encuestados trabaja en la documentación interna y del código. Desde el año pasado, la proporción de los que trabajan en documentación orientada al cliente ha disminuido en cuatro puntos porcentuales.
Herramientas de creación de documentación
Los editores de texto personalizables siguen siendo la herramienta preferida por los autores de documentación. Resultan un medio ligero, flexible y eficaz para editar texto y código, lo que los hace especialmente adecuados para redactar documentación.
Sin embargo, este año se ha producido un descenso de siete puntos porcentuales en el uso de editores de texto personalizables, unido a un aumento casi equivalente de seis puntos porcentuales en las páginas de GitHub. Mientras tanto, Confluence, un ejemplo destacado de documentación wiki colaborativa, mantiene su posición.
Del 3 % de los encuestados que utilizan una solución profesional de creación de ayuda, el 42 % prefiere las herramientas creadas a medida. Entre las opciones restantes, la única herramienta más nueva que destaca es Paligo, con una cuota del 5%. Las demás opciones populares son todas herramientas tradicionales ya establecidas.
Aunque más de la mitad de los que se dedican a la redacción técnica no han pensado en utilizar una herramienta profesional, un significativo 45 % está abierto a la idea.
Marcado
Markdown sigue siendo la opción predominante. Sin embargo, en comparación con el año pasado, se observa un claro cambio desde el Markdown estándar (7 puntos porcentuales menos) y las variantes de Markdown (4 puntos porcentuales menos) hacia las aplicaciones WYSIWYG y similares a Office (6 puntos porcentuales más). ¿Significa esto que el control sobre las fuentes está pasando a un segundo plano frente a la comodidad o la facilidad de uso?
Reutilización de contenidos y plantillas
Casi la mitad de los encuestados utiliza un enfoque estructurado para reutilizar el contenido. Sin embargo, el 32 % sigue copiando y pegando, posiblemente debido a las limitaciones de sus herramientas, lo que puede provocar incoherencias y ralentizar el proceso de documentación.
Comprobaciones automatizadas y calidad de la documentación
Solo el 13 % de los encuestados utiliza comprobaciones automatizadas en la documentación técnica. La gran mayoría escribe sus pruebas internamente en lugar de utilizar linters públicos, presumiblemente porque las pruebas se centran en las referencias, los enlaces y el marcado rotos. Para las comprobaciones lingüísticas y de estilo, se prefieren los correctores ortográficos integrados.
Documentación de API
Más de la mitad de los encuestados escribe referencias de API. Los desarrolladores se llevan la palma, pues un 81 % afirma escribir referencias de API. Le siguen roles como arquitectos (19 %), redactores técnicos (18 %) e ingenieros DevOps (17 %). Otros roles laborales están menos implicados en esta tarea, y los cargos más altos como los CIO, CEO y CTO tienen un pequeño porcentaje (7 %) implicado en esta actividad.
61 %
La mayoría, el 61 %, genera automáticamente referencias a la API directamente desde el código, una práctica indicativa de procesos de documentación eficientes. En cuanto a las herramientas, Swagger domina el panorama con una cuota del 84 %.
2/3
Aproximadamente dos tercios de los que automatizan siguen necesitando mejorar a mano sus contenidos generados automáticamente. Aunque la automatización acelera lo básico, la introducción manual es clave para el contexto y para añadir un toque personal a las referencias de la API.
Idiomas y localización
El inglés sigue siendo el idioma principal más popular para la documentación técnica. El chino ocupa un distante segundo lugar, perdiendo este año cuatro puntos porcentuales. El japonés ocupa el tercer lugar, habiendo ganado siete puntos porcentuales desde el año pasado.
Solo el 14 % de los encuestados traduce su documentación a otros idiomas, mientras que el 8 % se lo está planteando. Estas cifras no han cambiado significativamente desde el año pasado.
¡Gracias por el tiempo que nos ha dado!
Esperamos que nuestro informe le haya resultado útil. Comparta este informe con sus amigos y compañeros.
Si tiene alguna pregunta o sugerencia, no dude en ponerse en contacto con nosotros a través de surveys@jetbrains.com.