Contribuția la documentație

Contribuția la documentație este una dintre cele mai valoroase activități, deoarece îi ajută pe ceilalți să înțeleagă cadrul.

Cum se scrie?

Documentația este destinată în primul rând persoanelor care nu cunosc acest subiect. Prin urmare, ar trebui să îndeplinească mai multe puncte importante:

Începeți cu subiecte simple și generale. Treceți la subiecte mai avansate la sfârșit
Încercați să explicați subiectul cât mai clar posibil. De exemplu, încercați să explicați mai întâi subiectul unui coleg
Furnizați numai informațiile pe care utilizatorul trebuie să le știe cu adevărat pentru un anumit subiect
Asigurați-vă că informațiile pe care le furnizați sunt corecte. Testați fiecare cod
Fiți concis – reduceți la jumătate ceea ce scrieți. Și apoi nu ezitați să o faceți din nou
Folosiți evidențierea cu moderație, de la fonturi îngroșate la cadre de genul .[note]
Respectați standardul de codi ficare în cod

De asemenea, învățați sintaxa. Pentru o previzualizare a articolului în timpul scrierii, puteți utiliza editorul de previzualizare.

Mutații lingvistice

Engleza este limba principală, așa că modificările trebuie să fie în limba engleză. Dacă engleza nu este punctul dumneavoastră forte, utilizați DeepL Translator și alții vă vor verifica textul.

Traducerea în alte limbi se va face automat după aprobarea și punerea la punct a modificării dumneavoastră.

Modificări triviale

Pentru a contribui la documentație, trebuie să aveți un cont pe GitHub.

Cel mai simplu mod de a face o mică modificare în documentație este să folosiți linkurile de la sfârșitul fiecărei pagini:

Show on GitHub deschide versiunea sursă a paginii pe GitHub. Apoi, trebuie doar să apăsați butonul E și puteți începe să editați (trebuie să fiți logat pe GitHub)
Open preview deschide un editor în care puteți vedea imediat forma vizuală finală

Deoarece editorul de previzualizare nu are posibilitatea de a salva modificările direct pe GitHub, trebuie să copiați textul sursă în clipboard (folosind butonul Copy to clipboard) și apoi să îl lipiți în editorul de pe GitHub. Sub câmpul de editare se află un formular pentru trimitere. Aici, nu uitați să rezumați pe scurt și să explicați motivul modificării dvs. După trimitere, se creează o așa-numită pull request (PR), care poate fi editată în continuare.

Modificări mai mari

Este mai indicat să vă familiarizați cu elementele de bază ale lucrului cu sistemul de control al versiunilor Git decât să vă bazați exclusiv pe interfața GitHub. Dacă nu sunteți familiarizat cu Git, puteți consulta ghidul git – the simple guide și puteți lua în considerare utilizarea unuia dintre numeroșii clienți grafici disponibili.

Modificați documentația în felul următor:

pe GitHub, creați o bifurcație a depozitului nette/docs
clonați acest depozit pe computerul dvs.
apoi, efectuați modificări în ramura corespunzătoare
verificați dacă există spații în plus în text cu ajutorul instrumentului Code-Checker
salvați (confirmați) modificările
dacă sunteți mulțumit de modificări, împingeți-le pe GitHub în bifurcația dvs.
de acolo, trimiteți-le la depozitul nette/docs creând o pull request (PR)

Este obișnuit să primiți comentarii cu sugestii. Țineți evidența modificărilor propuse și încorporați-le. Adăugați modificările sugerate ca noi comisioane și retrimiteți-le la GitHub. Nu creați niciodată un nou pull request doar pentru a modifica unul existent.

Structura documentației

Întreaga documentație se găsește pe GitHub, în depozitul nette/docs. Versiunea curentă se află în ramura master, în timp ce versiunile mai vechi se află în ramuri precum doc-3.x, doc-2.x.

Conținutul fiecărei ramuri este împărțit în dosare principale care reprezintă domenii individuale ale documentației. De exemplu, application/ corespunde la https://doc.nette.org/en/application, latte/ corespunde la https://latte.nette.org, etc. Fiecare dintre aceste dosare conține subdosare care reprezintă mutații lingvistice (cs, en, …) și, opțional, un subdosar files cu imagini care pot fi inserate în paginile din documentație.