Guía de estilo de documentación

Aún no tenemos una guía de estilo oficial, pero el estilo actual de la documentación de OpenTelemetry está inspirado en las siguientes guías de estilo:

• Guía de estilo de documentación para desarrolladores de Google
• Guía de estilo de Kubernetes

Las siguientes secciones contienen orientación específica para el proyecto OpenTelemetry.

Lista de palabras de OpenTelemetry.io

Una lista de términos y palabras específicos de OpenTelemetry que se deben usar de manera uniforme en todo el sitio:

• OpenTelemetry y OTel
• Collector
• OTEP
• OpAMP

Para obtener una lista completa de los términos de OpenTelemetry y su definición, consulta el Glosario.

Asegúrate de que los nombres propios, como otros proyectos de CNCF o herramientas de terceros, estén escritos correctamente y utilicen la mayúscula original. Por ejemplo, escribe “PostgreSQL” en lugar de “postgre”. Para obtener una lista completa, consulta el archivo .textlintrc.yml.

Markdown

Las páginas del sitio están escritas en la sintaxis Markdown soportada por el renderizador Markdown Goldmark. Para ver la lista completa de extensiones Markdown soportadas, consulta Goldmark.

También puedes usar las siguientes extensiones de Markdown:

• Alertas
• Emojis: para ver la lista completa de emojis disponibles, consulta Emojis en la documentación de Hugo.

Alertas

Puedes escribir alertas usando la siguiente sintaxis extendida:

• Alertas de GitHub-flavored Markdown (GFM)
• Sintaxis de Obsidian callout para títulos de alerta personalizados

Aquí hay un ejemplo de cada una:

> [!TIP]
>
> Si estás escribiendo contenido nuevo, generalmente prefiere usar esta sintaxis
> de alerta de cita en bloque en lugar del
> [shortcode alert](https://www.docsy.dev/docs/content/shortcodes/#alert) de Docsy.

> [!WARNING] :warning: ¡Se requiere línea en blanco!
>
> Este sitio usa el formateador [Prettier], y requiere una línea vacía
> separando la etiqueta/título de la alerta del cuerpo de la alerta.

Estas se renderizan como:

Para más detalles sobre la sintaxis de alertas de cita en bloque de Hugo, consulta Alertas en la documentación de Hugo.

Verificaciones de Markdown

Para hacer cumplir estándares y consistencia en los archivos Markdown, todos los archivos deben seguir ciertas reglas, aplicadas por markdownlint. Para ver una lista completa, consulta los archivos .markdownlint.yaml y .markdownlint-cli2.yaml.

También aplicamos el formato de archivo de Markdown y eliminamos los espacios en blanco finales de los archivos. Esto impide la sintaxis de salto de línea de 2+ espacios; usa <br> en su lugar o reformatea tu texto.

Revisión ortográfica

Usa CSpell para asegurarte de que todo tu texto esté escrito correctamente. Para ver una lista de palabras específicas del sitio web de OpenTelemetry, consulta el archivo .cspell.yml.

Si cspell indica un error de “Unknown word”, verifica si escribiste la palabra correctamente. Si es así, agrega la palabra a la sección cSpell:ignore en la parte superior de tu archivo. Si no existe dicha sección, puedes agregarla al front matter de un archivo Markdown:

---
title: TítuloDeLaPágina
cSpell:ignore: <word>
---

Para cualquier otro archivo, agrega cSpell:ignore <word> en una línea de comentario apropiada para el contexto del archivo. Para un archivo YAML de entrada del registry, podría verse así:

# cSpell:ignore <word>
title: títuloDeEntradaDelRegistro

Formato de archivo

Usamos Prettier para aplicar el formato de archivos. Invócalo usando:

• npm run fix:format para formatear todos los archivos
• npm run fix:format:diff para formatear solo los archivos que han cambiado desde el último commit
• npm run fix:format:staged para formatear solo los archivos que están en staging para el próximo commit

Nombres de archivos

Todos los nombres de archivo deben estar en kebab case.

Corregir problemas de validación

Para aprender cómo corregir problemas de validación, consulta Verificaciones de pull request.