Guía de estilo de documentación

Terminología y estilo al escribir la documentación de OpenTelemetry.

The content of this page may be outdated and some links may be invalid. A newer version of this page exists in English.

More information ...

To see the changes to the English page since this page was last updated: visit GitHub compare 400dcdab..4aa05a4d and search for content/en/docs/contributing/style-guide.md.

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:

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

Nota

Muchos requisitos de nuestra guía de estilo se pueden aplicar ejecutando automatización: antes de enviar un pull request (PR), ejecuta npm run fix:all en tu máquina local y haz commit de los cambios.

Si encuentras errores o verificaciones de PR fallidas, lee sobre nuestra guía de estilo y aprende qué puedes hacer para corregir ciertos problemas comunes.

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:

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:

Consejo