Cum să contribuiți la documentație

Contribuția la documentație este una dintre cele mai benefice activități, deoarece îi ajutați pe alții să înțeleagă framework-ul.

Cum să scrieți?

Documentația este destinată în principal persoanelor care se familiarizează cu subiectul. Prin urmare, ar trebui să îndeplinească câteva puncte importante:

Începeți de la simplu și general. Treceți la subiecte mai avansate abia la sfârșit.
Încercați să explicați lucrul cât mai bine posibil. Încercați, de exemplu, să explicați mai întâi subiectul unui coleg.
Furnizați doar informațiile de care utilizatorul are nevoie cu adevărat pentru subiectul respectiv.
Verificați dacă informațiile dvs. sunt într-adevăr adevărate. Testați fiecare cod.
Fiți concis – scurtați ceea ce scrieți la jumătate. Și apoi, dacă este necesar, încă o dată.
Economisiți evidențiatoarele de orice fel, de la text îngroșat la cadre precum .[note].
În coduri respectați Coding Standard.

Însușiți-vă și sintaxa. Pentru previzualizarea articolului în timpul scrierii, puteți utiliza editorul cu previzualizare.

Versiuni lingvistice

Limba principală este engleza, modificările dvs. ar trebui deci să fie și în engleză. Dacă engleza nu este punctul dvs. forte, utilizați DeepL Translator și ceilalți vă vor verifica textul.

Traducerea în celelalte limbi va fi efectuată automat după aprobarea și finisarea modificării dvs.

Modificări triviale

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

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

Arată pe GitHub deschide forma sursă a paginii respective pe GitHub. Apoi este suficient să apăsați butonul E și puteți începe editarea (este necesar să fiți autentificat pe GitHub).
Deschide previzualizarea deschide editorul, unde vedeți imediat și forma vizuală finală.

Deoarece editorul cu previzualizare nu are posibilitatea de a salva modificările direct pe GitHub, este necesar ca după finalizarea modificărilor să copiați textul sursă în clipboard (cu butonul Copy to clipboard) și apoi să-l lipiți în editorul de pe GitHub. Sub câmpul de editare se află formularul de trimitere. Aici nu uitați să rezumați pe scurt și să explicați motivul modificării dvs. După trimitere se creează așa-numitul pull request (PR), care poate fi editat ulterior.

Modificări mai mari

Mai potrivit decât utilizarea interfeței GitHub este să fiți familiarizat cu elementele de bază ale lucrului cu sistemul de versionare Git. Dacă nu stăpâniți lucrul cu Git, puteți consulta ghidul git – the simple guide și eventual să utilizați unul dintre multele clienți grafici.

Modificați documentația în acest mod:

pe GitHub creați un fork al depozitului nette/docs
clonați acest depozit pe computerul dvs.
apoi în ramura corespunzătoare efectuați modificările
verificați spațiile în exces din text folosind instrumentul Code-Checker
salvați modificările (commit)
dacă sunteți mulțumit de modificări, trimiteți-le (push) pe GitHub în fork-ul dvs.
de acolo le trimiteți către depozitul nette/docs creând un pull request (PR)

Este obișnuit să primiți comentarii cu observații. Urmăriți modificările propuse și încorporați-le. Adăugați modificările propuse ca noi commit-uri și retrimiteți-le pe GitHub. Nu creați niciodată un nou pull request pentru a modifica unul existent.

Structura documentației

Întreaga documentație este găzduită pe GitHub în depozitul nette/docs. Versiunea curentă este în master, versiunile mai vechi sunt plasate în ramuri precum doc-3.x, doc-2.x.

Conținutul fiecărei ramuri este împărțit în directoare principale reprezentând domeniile individuale ale documentației. De exemplu, application/ corespunde https://doc.nette.org/ro/application, latte/ corespunde https://latte.nette.org etc. Fiecare dintre aceste directoare conține subdirectoare reprezentând versiunile lingvistice (cs, en, …) și eventual subdirectorul files cu imagini, care pot fi inserate în paginile din documentație.