La mayoría de los sitios web de documentación empresarial que incluyen bloques de código utilizan estilos que indican marcadores de posición. Se supone que la intención debe quedar clara y que los lectores deben saber qué deben modificar, pero la experiencia deja mucho que desear.
Estos mismos estilos también se utilizan para resaltar texto, etiquetas de la interfaz de usuario o sintaxis en otras partes de la documentación. Entre los marcadores de posición más comunes que utilizan los equipos de redacción técnica para identificar bloques de código —y que se emplean como otros estilos— se incluyen:
- Cursiva
- {Acordeones}
- Negrita
- ejemplo_nombre_##
- MAYÚSCULAS
- Alguna combinación de lo anterior.
- Algo completamente diferente
Esta superposición hace que el seguimiento y la gestión de los marcadores de posición sean más complejos de lo que deberían. A pequeña escala, esto puede parecer una molestia. Pero a medida que las bibliotecas de documentación crecen y se extienden entre equipos y a lo largo de los años, crea problemas tanto para los autores como para los lectores. Lo que se supone que debe simplificar la gestión de los marcadores de posición, en realidad la complica, ya que el mismo estilo se reutiliza en otros lugares.
El resultado puede ponerte en una situación ya conocida: debes averiguar la convención de los marcadores de posición e intentar actualizarlos todos si quieres tener éxito. Si se te pasa por alto un marcador de posición, es posible que el comando no funcione como se espera. Pueden surgir otros problemas, como errores, configuraciones inesperadas o incluso ajustes que no sabías que se podían modificar. Otros enfoques de bloques de código solo llegan hasta cierto punto:
- Los bloques estáticos (con o sin resaltado sintáctico) son esenciales cuando ya conoces los valores. Son rápidos y están listos para copiar y ejecutar. Son la mejor opción cuando no necesitas modificar nada.
- Los editores en línea van al extremo opuesto y te permiten actualizar el texto directamente dentro del bloque de código, pero a menudo a costa del contexto: la función de deshacer deja de ser fiable y los pequeños errores borran la estructura que necesitas.
- Los editores de API para desarrolladores te permiten probar solicitudes en tiempo real y son ideales cuando el público principal son desarrolladores que trabajan directamente con API. Sin embargo, la documentación empresarial tiene funciones y casos de uso más amplios, y ese estilo de interactividad suele faltar cuando aún podría aportar valor añadido.
Reducir la brecha con bloques de código interactivos
Nuestros bloques de código interactivos cierran esta brecha al convertir una parte históricamente frágil de la documentación (el marcador de posición) en algo claro, editable y escalable.
Obtienes el mismo comando que antes con el mismo formato y estructura, solo que ahora los marcadores de posición se han convertido en campos editables. Cada uno tiene una etiqueta clara (como antes), por lo que no tienes que interpretar símbolos ni basarte en conjeturas.
Puedes actualizar los valores directamente dentro del bloque, sin perder de vista el contexto que lo rodea. Esto significa que ves el ejemplo, el resto del contenido de la página y tus entradas, todo en un mismo lugar. Esto puede ayudarte a crear un fragmento más relevante antes de hacer clic en «Copiar».
Puedes modificar esos valores antes de copiarlos o dejarlos tal cual y editarlos más tarde en otro editor. En cualquier caso, la estructura permanece igual y lo que copias refleja exactamente lo que ves en el bloque. Los marcadores de posición de un bloque de código que tienen el mismo nombre están vinculados entre sí. Cuando cambias el valor de un campo de marcador de posición situado encima del bloque de código, todos los campos vinculados se actualizan al mismo tiempo, lo que te permite editar de forma más coherente los campos que tienen el mismo valor de marcador de posición. Esto ayuda a reducir los posibles errores de búsqueda y sustitución al trabajar en un editor de texto.
El cambio en la experiencia
Este cambio resuelve dos problemas a la vez. Para los lectores, reduce las conjeturas y evita errores. Ya no hay que descifrar llaves ni corchetes angulares. Para los autores, separa la semántica del estilo, lo que permite realizar un seguimiento, auditar y actualizar los marcadores de posición mediante programación. Esto permite el control de versiones, las reglas de validación y la coherencia en todos los entornos. Las inconsistencias heredadas se corrigen sobre la marcha, lo que facilita el mantenimiento general de la biblioteca.
Los bloques de código interactivos convierten una de las partes más difíciles de la documentación —los marcadores de posición basados en el estilo— en algo preciso, fácil de mantener y rápido de usar. La experiencia se percibe como intencionada, en lugar de improvisada. Y, por primera vez, la gestión de ejemplos de código a gran escala genera oportunidades de mejora en lugar de obstáculos.
Ya disponible en Software, SaaS y más
Esta experiencia ya está disponible en nuestro sitio de documentación para Software (versiones 11.42, 11.40, 11.36 y 11.32), SaaS y otros sitios relacionados en https://documentation.commvault.com/.
Pruébalos la próxima vez que navegues y encuentres un bloque de código: edita algunos campos, haz clic en «Copiar» y comprueba lo fácil que es empezar a trabajar con él una vez que lo hayas importado a tu editor.
Notas:
- Revisa cuidadosamente cualquier código antes de ejecutarlo, ya sea de un bloque de código interactivo o estático.
- Cuando actualizas una página tras cambiar los marcadores de posición en un bloque de código interactivo, todos los marcadores de posición modificados vuelven a sus valores predeterminados.
Más información sobre el uso de bloques de código aquí.
