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?

87%

Documentación interna

63%

Documentación del código

53%

Documentación destinada al cliente

1%

Otro/a

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?

46%

39%

Un editor de texto personalizable

49%

32%

Confluence u otra plataforma wiki

28%

30%

Una aplicación de oficina

24%

23%

Google Docs

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

42%

Solución personalizada

29%

Adobe FrameMaker

22%

Help & Manual

9%

Adobe RoboHelp

7%

ClickHelp

7%

MadCap Flare

5%

AuthorIt

5%

Paligo

10%

Otro/a

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?

77%

70%

Markdown

18%

24%

No lo sé seguro/Utilizo un editor WYSIWYG o una aplicación tipo Office

13%

9%

Una variante personalizada de Markdown

5%

6%

XML / DITA / DocBook / etc.

5%

5%

AsciiDoc

4%

4%

reStructuredText

4%

3%

Otro/a

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?

47%

Sí, almaceno contenidos reutilizables en fragmentos y los referencio desde diferentes documentos

32%

No, mis herramientas no admiten la reutilización de contenidos, así que copio y pego contenidos similares

21%

No, no necesito reutilizar contenidos

¿Utiliza plantillas para acelerar el proceso de escritura?

¿Para qué tipo de tareas configura plantillas?

78%

Diferentes tipos de temas/documentos

48%

Contenido repetido como bloques de amonestación

29%

Elementos de marcado complejos

¿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?

61%

Marcado roto

56%

Enlaces externos rotos

53%

Recursos que faltan

52%

Referencias internas rotas

47%

Estructura del documento rota

38%

Muestras de código roto

6%

Otro/a

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

54%

Sí, mi editor tiene un corrector ortográfico/gramatical integrado

22%

No, confiamos en las revisiones

13%

Uso un servicio externo

12%

Tenemos controles lingüísticos automatizados

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

81%

68%

Desarrollador, programador o ingeniero de software

19%

11%

Arquitecto

18%

14%

Escritor técnico

17%

13%

Ingeniero DevOps, desarrollador de infraestructuras

¿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?

84%

Swagger

9%

ReDoc

15%

Otro/a

¿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?

62%

Inglés

18%

Chino

13%

Japonés

2%

Francés

1%

Español

1%

Coreano

1%

Alemán

2%

Otro/a

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