|
| 1 | +--- |
| 2 | +title: Guía de estilo de documentación |
| 3 | +description: |
| 4 | + Terminología y estilo al escribir la documentación de OpenTelemetry. |
| 5 | +linkTitle: Guía de estilo de documentación |
| 6 | +weight: 20 |
| 7 | +default_lang_commit: 99f0ae5760038d51f9e9eb376bb428a2caca8167 |
| 8 | +cSpell:ignore: open-telemetry opentelemetryio postgre style-guide textlintrc |
| 9 | +--- |
| 10 | + |
| 11 | +Aún no tenemos una guía de estilo oficial, pero el estilo actual de la |
| 12 | +documentación de OpenTelemetry está inspirado en las siguientes guías de estilo: |
| 13 | + |
| 14 | +- [Guía de estilo de documentación de para desarrolladores Google](https://developers.google.com/style) |
| 15 | +- [Guía de estilo de documentación de Kubernetes](https://kubernetes.io/docs/contribute/style/style-guide/) |
| 16 | + |
| 17 | +Las siguientes secciones contienen indicaciones específicas para el proyecto |
| 18 | +OpenTelemetry. |
| 19 | + |
| 20 | +{{% alert title="Note" color="primary" %}} |
| 21 | + |
| 22 | +Muchos de los requisitos de nuestra guía de estilo se pueden aplicar |
| 23 | +automaticamente: antes de enviar un |
| 24 | +[pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request) |
| 25 | +(PR), ejecute `npm run fix:all` en su máquina local y confirme los cambios. |
| 26 | + |
| 27 | +Si se producen errores o [fallan las comprobaciones de su PR](../pr-checks), lea |
| 28 | +nuestra guía de estilo y aprenda qué puede hacer para solucionar ciertos asuntos |
| 29 | +comunes. |
| 30 | + |
| 31 | +{{% /alert %}} |
| 32 | + |
| 33 | +## Lista de palabras de OpenTelemetry.io {#opentelemetryio-word-list} |
| 34 | + |
| 35 | +Una lista de términos y palabras específicos de OpenTelemetry que se deben usar |
| 36 | +de manera uniforme en todo el sitio: |
| 37 | + |
| 38 | +- [OpenTelemetry](/docs/concepts/glossary/#opentelemetry) y |
| 39 | + [OTel](/docs/concepts/glossary/#otel) |
| 40 | +- [Collector](/docs/concepts/glossary/#collector) |
| 41 | +- [OTEP](/docs/concepts/glossary/#otep) |
| 42 | +- [OpAMP](/docs/concepts/glossary/#opamp) |
| 43 | + |
| 44 | +Para obtener una lista completa de los términos de OpenTelemetry y su |
| 45 | +definición, consulte [Glosario](/docs/concepts/glossary/). |
| 46 | + |
| 47 | +Asegúrese de que los nombres propios, como otros proyectos de CNCF o |
| 48 | +herramientas de terceros, estén escritos correctamente y utilicen la mayúscula |
| 49 | +original. Por ejemplo, escriba "PostgreSQL" en lugar de "postgre". Para obtener |
| 50 | +una lista completa, consulte el archivo |
| 51 | +[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml). |
| 52 | + |
| 53 | +{{% alert title="Tip" %}} |
| 54 | + |
| 55 | +Ejecute `npm run check:text` para verificar que todos los términos y palabras |
| 56 | +estén escritos correctamente. |
| 57 | + |
| 58 | +Ejecute `npm run check:text -- --fix` para corregir términos y palabras que no |
| 59 | +están escritos correctamente. |
| 60 | + |
| 61 | +{{% /alert %}} |
| 62 | + |
| 63 | +## Estándares de Markdown {#markdown-standards} |
| 64 | + |
| 65 | +Para hacer cumplir los estándares y la coherencia de los archivos Markdown, |
| 66 | +todos los archivos deben seguir ciertas reglas, impuestas por |
| 67 | +[markdownlint](https://github.com/DavidAnson/markdownlint). Para obtener una |
| 68 | +lista completa, consulte el archivo |
| 69 | +[`.markdownlint.json`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.json). |
| 70 | + |
| 71 | +Ejecute `npm run check:markdown` para verificar que todos los archivos siguen el |
| 72 | +estándar. |
| 73 | + |
| 74 | +Ejecute `npm run fix:markdown` para corregir problemas de formato relacionados |
| 75 | +con Markdown. |
| 76 | + |
| 77 | +## Revisión ortográfica {#spell-checking} |
| 78 | + |
| 79 | +Utilice [CSpell](https://github.com/streetsidesoftware/cspell) para asegurarse |
| 80 | +de que todo su texto esté escrito correctamente. Para obtener una lista de |
| 81 | +palabras específicas del sitio web OpenTelemetry, consulte el archivo |
| 82 | +[`.cspell.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.cspell.yml). |
| 83 | + |
| 84 | +Ejecute `npm run check:spelling` para verificar que todas las palabras estén |
| 85 | +escritas correctamente. Si `cspell` indica un error de `Palabra desconocida`, |
| 86 | +verifique si escribió esa palabra correctamente. Si es así, agregue esta palabra |
| 87 | +a la sección `cSpell:ignore` en la parte superior de su archivo. Si no existe |
| 88 | +dicha sección, puede agregarla al principio de un archivo Markdown: |
| 89 | + |
| 90 | +```markdown |
| 91 | +--- |
| 92 | +title: TítuloDeLaPágina |
| 93 | +cSpell:ignore: <word> |
| 94 | +--- |
| 95 | +``` |
| 96 | + |
| 97 | +Para cualquier otro archivo, agregue `cSpell:ignore <word>` en una línea de |
| 98 | +comentario apropiada para el contexto del archivo. Para un archivo YAML de |
| 99 | +entrada [registry](/ecosystem/registry/), podría verse así: |
| 100 | + |
| 101 | +```yaml |
| 102 | +# cSpell:ignore <word> |
| 103 | +title: TítuloDeEntradaDelRegistro |
| 104 | +``` |
| 105 | +
|
| 106 | +Las herramientas del sitio web normalizan los diccionarios específicos de la |
| 107 | +página (es decir, las listas de palabras `cSpell:ignore`), eliminando palabras |
| 108 | +duplicadas, borrando palabras en la lista de palabras global y ordenando las |
| 109 | +palabras. Para normalizar los diccionarios específicos de la página, ejecute |
| 110 | +`npm run fix:dict`. |
| 111 | + |
| 112 | +## Formato de archivo {#file-format} |
| 113 | + |
| 114 | +Para hacer cumplir un estándar determinado sobre cómo se estructuran los |
| 115 | +archivos, todos los archivos deben estar formateados por |
| 116 | +[prettier](https://prettier.io). Ejecute `npm run fix:format` antes de enviar un |
| 117 | +PR, o ejecutarlo después y enviar una confirmación adicional. |
| 118 | + |
| 119 | +## Nombres de archivos {#file-names} |
| 120 | + |
| 121 | +Todos los nombres de archivo deben estar en |
| 122 | +[kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). Ejecute |
| 123 | +`npm run fix:filenames` para cambiar automáticamente el nombre de sus archivos. |
0 commit comments