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.

¿Qué tipo de documentación redacta?

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.

¿Qué herramientas utiliza para crear documentación?

¿Qué solución de creación de documentación de ayuda profesional utiliza?

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.

¿Le satisface su solución actual?

Un llamativo 30 % de los que utilizan una herramienta de creación de documentación de ayuda busca algo mejor.

¿Ha pensado en utilizar una herramienta profesional para la redacción técnica?

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?

Díganos lo que piensa

¿Qué lenguaje de marcado utiliza para escribir documentación técnica?

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.

¿Reutiliza contenidos entre distintos documentos o guías?

¿Utiliza plantillas para acelerar el proceso de escritura?

¿Para qué tipo de tareas configura plantillas?

¿Crea plantillas parametrizadas (por ejemplo, plantillas que contengan variables)?

El 69 % de los encuestados no utiliza plantillas para agilizar la escritura, pero de los que sí lo hacen, la mayoría las utiliza para distintos tipos de documentos. En cuanto a las plantillas dinámicas con variables, las opiniones están bastante divididas.

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.

¿Dispone de controles automatizados para la documentación técnica?

¿De qué tipos de comprobaciones dispone?

¿Automatiza las comprobaciones lingüísticas y de estilo?

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.

¿Redacta usted las referencias de la API?

Redacción de referencias API en función del puesto de trabajo

¿Genera automáticamente la referencia API a partir del código?

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 %.

¿Qué herramientas utiliza?

¿Necesita ampliar las referencias API generadas automáticamente con contenido escrito manualmente?

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.

¿Cuál es el idioma principal en el que redacta la documentación?

¿Localiza la documentación?

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.

Redacción técnica:

2023

¡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.