Ahorrar tiempo y evitar tareas repetitivas con código DRY
Los programadores tienen un mantra para simplificar el código y reducir las duplicaciones: «No te repitas» (DRY, Don’t Repeat Yourself). Esta frase les recuerda que deben reutilizar los fragmentos de código más frecuentes en diferentes archivos que pueden aparecer en distintas ubicaciones. Gracias al principio DRY, se ahorra tiempo cuando se quieren implementar actualizaciones en varias ubicaciones y se reduce la posibilidad de errores.
De hecho, este principio también resulta útil para el equipo de documentación de Fastly, del que formo parte. Usamos determinadas frases y expresiones docenas de veces en la documentación, y nos ha sido muy útil almacenar algunas de ellas en una ubicación que sirva como referencia en todo tipo de guías. Esto nos permite estandarizar la documentación, reducir los errores de copia y pega, y eliminar algunos de los problemas relacionados con las actualizaciones de la documentación debidos a cambios en las interfaces, lo cual se traduce en una respuesta más rápida a dichos cambios y en actualizaciones más veloces. Además, nos capacita para gestionar las versiones traducidas de la documentación. Los contenidos reutilizados nos han permitido traducir rápidamente del inglés al japonés, con la posibilidad de añadir más idiomas sin complicaciones.
Y como nos parece tan útil para nuestro flujo de trabajo, creí interesante mostrar cómo lo hicimos por si puede ser de ayuda. Vamos a verlo.
Para poder adherirnos al principio DRY, aprovechamos una funcionalidad interna de nuestro generador estático de sitios, Jekyll. Jekyll incorpora un método de reutilización de contenidos llamado archivos de datos que nos permitió crear archivos que contenían emparejamientos clave:valor a los que nos referimos como claves DRY.
Crear claves DRY fue fácil. Bastó con crear una carpeta de _datos en el repositorio y un par de archivos YML para almacenar las claves DRY: uno para las claves DRY en inglés (en.yml) y otro para las claves DRY en japonés (ja.yml). Organizamos las claves DRY en pares clave:valor en cada archivo YML. Por ejemplo:
my-dry-key: “Insert text for DRY key.”Nota: ambos archivos YML contienen el mismo nombre de clave, pero el valor se traduce al idioma de destino.
La parte más difícil consistió en determinar qué textos convertir en claves DRY. Decidimos crear claves DRY para los encabezados de los cuadros de alerta que aparecen en el sitio de documentación, porque se citan muy a menudo:
alert-leader-tip: "TIP"
alert-leader-note: "NOTE"
alert-leader-important: CAUTION
alert-leader-warning: "WARNING" También creamos claves DRY para los pasos más habituales citados a lo largo y ancho del sitio de documentación. Seguramente te suenen:
step-login: "Log in to the Fastly web interface."
step-login-configure: "Log in to the Fastly web interface and click the **Configure** link."
step-login-account: "Log in to the Fastly web interface and click the **Account** link from the [user menu](/en/guides/about-the-web-interface-controls#about-the-user-menu. Your account information appears."
step-select-service: "From the **All services** page, select the appropriate service. You can use the search box to search by ID, name, or domain."
step-click-edit: "Click the **Edit configuration** button and then select the option to clone the active version. The Domains page appears."
step-click-origins-tab: "Click the **Origins** link. The Origins page appears."
step-click-settings-tab: "Click the **Settings** link. The Settings page appears."
step-click-content-tab: "Click the **Content** link. The Content page appears."
step-activate-deploy: "Click the **Activate** button to deploy your configuration changes."¿Cómo funciona todo esto en la práctica? Para usar una clave DRY en la documentación, la referenciamos simplemente en una etiqueta Liquid de la forma siguiente: {% t my-dry-key %}.
Nuestro complemento Jekyll personalizado lee cada etiqueta DRY y genera el valor de la clave DRY. Por ejemplo, observa esta sección de la guía Carga de VCL personalizado:
Este es el aspecto que tiene esta guía tras bambalinas:
1. {% t step-login %}
2. {% t step-select-service %}
3. {% t step-click-edit %}
4. Click the **Custom VCL** tab. The Custom VCL page appears.
5. Click the **Upload a new VCL file** button. The Upload a new VCL file page appears.La t indica que el código (como por arte de magia) debería usar el idioma de la página para obtener la versión apropiada traducida del texto DRY. Traducir es caro, porque la mayoría de servicios de traducción calculan el precio por palabras. Las claves DRY en japonés nos ayudan a ahorrar costes porque podemos pagar por tener una frase traducida una vez pero que se utiliza en varios sitios.
Para el despliegue inicial de nuestras claves DRY, tuvimos que buscar y reemplazar varias veces para insertar las claves DRY en el espacio adecuado de la documentación. Pero ahora, si surge algún cambio en la interfaz de Fastly, podemos ahorrar tiempo por nuestra cuenta al tener que actualizar solo una ubicación central para que el cambio aparezca en todo el sitio. Esto nos permite realizar actualizaciones de manera más rápida y reducir el riesgo de cometer errores u olvidarnos de alguna guía que necesitaba actualizarse.
Además, este sistema permite escalar cuando se añaden nuevas traducciones de la documentación. Solo habría que tomar el archivo de claves DRY existente, copiarlo con un nombre distinto y traducir los valores dichas claves.
Hay un mayor trabajo detrás que requeriría algo más de explicación de nuestro sistema de traducción de cosecha propia, así que lo compartiremos en otra entrada del blog.
