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 es clarayque los lectores saben qué deben modificar,pero la experiencia deja 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 seguimientoyla 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 crecenyse extienden entre equiposya 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 de sintaxis) son esenciales cuando ya conoces los valores. Son rápidosyestán listos para copiaryejecutar. Son la mejor opción cuando no necesitas modificar nada.
- Los editores en línea van al otro extremoyte permiten actualizar el texto directamente dentro del bloque de código,pero a menudo a expensas del contexto: la función de deshacer deja de ser fiableylos pequeños errores borran la estructura que necesitas.
- Los editores de API para desarrolladores te permiten probar solicitudes en tiempo realyson ideales cuando el público principal son desarrolladores que trabajan directamente con API. Sin embargo,la documentación empresarial tiene funcionesycasos 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,editableyescalable.
Obtienes el mismo comando que antes con el mismo formatoyestructura,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áginaytus entradas,todo en un mismo lugar. Esto puede ayudarte a crear un fragmento más relevante antes de hacer clic en «Copiar».
Puedes cambiar esos valores antes de copiarlos o dejarlos tal cualyeditarlos más tarde en otro editor. En cualquier caso,la estructura se mantiene igualylo 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 se vinculan 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úsquedaysustitución al trabajar en un editor de texto.
El cambio de experiencia
Este cambio resuelve dos problemas a la vez. Para los lectores,reduce las conjeturasyevita 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,auditaryactualizar los marcadores de posición mediante programación. Esto permite el control de versiones,las reglas de validaciónyla 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 manteneryrápido de usar. La experiencia se percibe como intencionada en lugar de improvisada. Y,por primera vez,gestionar ejemplos de código a gran escala genera oportunidades de mejora en lugar de obstáculos.
Ahora en directo en Software,SaaSymás
Esta experiencia ya está disponible en nuestro sitio de documentación para Software (versiones 11,42,11:40,11,36y11,32),SAASyotros sitios relacionados en https://documentation.commvault.com/.
Pruébalos la próxima vez que naveguenyencuentren un bloque de código: edita algunos campos,haz clic en «Copiar»ycomprueba 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 después de 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í.
