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 de para desarrolladores Google
• Guía de estilo de documentación de Kubernetes

Las siguientes secciones contienen indicaciones específicas 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, consulte Glosario.

Asegúrese 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, escriba “PostgreSQL” en lugar de “postgre”. Para obtener una lista completa, consulte el archivo .textlintrc.yml.

Estándares de Markdown

Para hacer cumplir los estándares y la coherencia de los archivos Markdown, todos los archivos deben seguir ciertas reglas, impuestas por markdownlint. Para obtener una lista completa, consulte el archivo .markdownlint.json.

Ejecute npm run check:markdown para verificar que todos los archivos siguen el estándar.

Ejecute npm run fix:markdown para corregir problemas de formato relacionados con Markdown.

Revisión ortográfica

Utilice CSpell para asegurarse de que todo su texto esté escrito correctamente. Para obtener una lista de palabras específicas del sitio web OpenTelemetry, consulte el archivo .cspell.yml.

Ejecute npm run check:spelling para verificar que todas las palabras estén escritas correctamente. Si cspell indica un error de Palabra desconocida, verifique si escribió esa palabra correctamente. Si es así, agregue esta palabra a la sección cSpell:ignore en la parte superior de su archivo. Si no existe dicha sección, puede agregarla al principio de un archivo Markdown:

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

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

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

Las herramientas del sitio web normalizan los diccionarios específicos de la página (es decir, las listas de palabras cSpell:ignore), eliminando palabras duplicadas, borrando palabras en la lista de palabras global y ordenando las palabras. Para normalizar los diccionarios específicos de la página, ejecute npm run fix:dict.

Formato de archivo

Para hacer cumplir un estándar determinado sobre cómo se estructuran los archivos, todos los archivos deben estar formateados por prettier. Ejecute npm run fix:format antes de enviar un PR, o ejecutarlo después y enviar una confirmación adicional.

Nombres de archivos

Todos los nombres de archivo deben estar en kebab case. Ejecute npm run fix:filenames para cambiar automáticamente el nombre de sus archivos.