Ghid de stil al documentației

We don’t have an official style guide yet, but the current OpenTelemetry documentation style is inspired by the following style guides:

• Ghid de stil al documentației Google Developer
• Stil al documentației Kubernetes Style Guide

Următoarele secțiuni conțin îndrumări specifice proiectului OpenTelemetry.

Listă de cuvinte OpenTelemetry.io

O listă de termeni și cuvinte specifice OpenTelemetry care trebuie utilizate în mod consecvent pe tot site-ul:

• OpenTelemetry și OTel
• Collector
• OTEP
• OpAMP

Pentru o listă completă a termenilor OpenTelemetry și definiția acestora, vezi Glosar.

Asigură-te că substantivele proprii, cum ar fi alte proiecte CNCF sau instrumente terțe, sunt scrise corect și folosesc majusculele originale. De exemplu, scrie „PostgreSQL” în loc de „postgre”. Pentru o listă completă, verifică fișierul .textlintrc.yml.

Markdown

Paginile site-ului sunt scrise în sintaxa Markdown acceptată de programul de randare Markdown Goldmark. Pentru lista completă a extensiilor Markdown acceptate, vezi Goldmark.

De asemenea, poți utiliza următoarele extensii Markdown:

• Alerte
• Emoji: pentru lista completă a emojiilor disponibile, vezi Emoji din documentele Hugo.

Alerte

Poți scrie alerte folosind următoarea sintaxă extinsă:

• Markdown cu stil GitHub (GFM) alerts
• Sintaxa Obsidian callout pentru titluri de alerte personalizate

Iată un exemplu pentru fiecare:

> [!TIP]
>
> Dacă scrii conținut nou, în general, preferă folosirea acestei sintaxe de alertă cu citate bloc
> în loc de sintaxa Docsy
> [alert shortcode](https://www.docsy.dev/docs/content/shortcodes/#alert).

> [!WARNING] :warning: Este necesară o linie goală!
>
> Acest site folosește formatorul [Prettier] și necesită o linie goală care să separe eticheta/titlul alertei de corpul alertei.

Acestea se redau astfel:

Pentru detalii despre sintaxa alertelor pentru citate bloc, consultă Alerts din documentația Docsy.

Referințe de link

Când utilizezi Markdown linkuri de referință, preferă forma restrânsă [text][] în locul formei shortcut [text]. Deși ambele sunt valide CommonMark, forma shortcut nu este recunoscută în mod constant de toate instrumentele Markdown. În special, dacă scrii [exemplu] și uiți definiția, linter-ul markdownlint nu te va avertiza¹ – textul este redat silențios ca literal [exemplu] în loc de link. Cu forma restrânsă [exemplu][], linter-ul surprinde imediat definiția lipsă.

Acest lucru este impus de regula personalizată no-shortcut-ref-link. Rulează npm run fix:markdown pentru a converti automat referințele la comenzi rapide.

Verificări Markdown

Pentru a aplica standarde și consecvență pentru fișierele Markdown, toate fișierele ar trebui să respecte anumite reguli, impuse de markdownlint. Pentru o listă completă, consultă fișierele .markdownlint.yaml și .markdownlint-cli2.yaml.

Când există excepții legitime de la o regulă, utilizează directiva markdownlint-disable pentru a suprima avertismentele privind regula. Pentru detalii, vezi documentația markdownlint.

De asemenea, aplicăm Markdown format fișier și eliminăm spațiile albe de la sfârșit din fișiere. Acest lucru exclude sintaxa de sfârșit de linie de peste 2 spații; utilizează <br> în schimb sau reformează textul.

Verificarea ortografiei

Folosește CSpell pentru a te asigura că tot textul tău este scris corect.

Dacă cspell raportează un „Cuvânt necunoscut”, verifică dacă ai scris cuvântul corect. Dacă da, adaugă cuvântul într-una dintre aceste locații:

• O listă cSpell:ignore locală în pagina principală. Pentru detalii, vezi mai jos.

• Fișierul tău cu lista de cuvinte specifică setărilor regionale

• Lista generală de cuvinte all-words.txt

Lista cSpell:ignore locală a paginii {#page-local-cSpell:ignore-list}

Dacă cuvântul necunoscut apare doar pe o singură pagină sau pe câteva pagini, adăugă-l la o listă cSpell:ignore de tip page local în partea de sus a paginii:

---
title: PageTitle
cSpell:ignore: <word>
---

Pentru fișierele non-Markdown, adăugă cSpell:ignore <cuvânt> într-o linie de comentarii corespunzătoare fișierului. De exemplu, într-un fișier YAML cu intrare registry, ar putea arăta astfel:

# cSpell:ignore <word>
title: registryEntryTitle

Fișiere cu listă de cuvinte

Dacă cuvântul necunoscut apare pe mai multe pagini sau este un termen tehnic, adăugă-l în fișierul cu lista de cuvinte specific setărilor regionale. Fișierele cu lista de cuvinte se află în directorul .cspell/.

Dacă cuvântul este scris corect în toate setările regionale, cum ar fi opamp, adăugă-l în fișierul all-words.txt.

Formatul fișierului

Folosim Prettier pentru a impune formatarea fișierelor. Invocă-l folosind:

• npm run fix:format pentru a formata toate fișierele
• npm run fix:format:diff pentru a formata doar fișierele care s-au modificat de la ultimul commit
• npm run fix:format:staged pentru a formata doar fișierele care sunt modificate pentru următorul commit

Nume de fișiere

Toate numele fișierelor ar trebui să fie în kebab case.

Rezolvarea problemelor de validare

Pentru a afla cum să remediezi problemele de validare, vezi verificările Pull request-ului.