Scrierea documentației

Contribuția la documentație este una dintre cele mai satisfăcătoare activități, deoarece îi ajutați pe alții să înțeleagă cadrul.

Modificări rapide

Cel mai simplu mod de a edita textul din documentație este să folosiți legăturile din partea de jos a 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 editarea (trebuie să fiți conectat la GitHub)
• Open preview deschide editorul, unde puteți vedea și forma vizuală rezultată.

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 GitHub când ați terminat de editat. Sub caseta de editare se află un formular de trimitere. Nu uitați să rezumați și să explicați pe scurt motivul modificării dvs. aici. Odată trimisă, va fi creată o cerere de tip pull request care poate fi editată în continuare.

Cum se scrie?

Documentația se adresează în principal persoanelor care nu cunosc acest subiect. Prin urmare, ar trebui să îndeplinească mai multe puncte importante:

• Când scrieți, începeți de la simplu și general. Treceți la subiecte mai avansate la sfârșit.
• Includeți numai informațiile pe care utilizatorul trebuie să le știe cu adevărat despre subiect.
• Verificați dacă informațiile dvs. sunt de fapt adevărate. Testați mai întâi codul înainte de a-l da.
• Fiți concis – reduceți la jumătate ceea ce scrieți. Și apoi fă-o din nou.
• Încercați să explicați cât mai bine subiectul. De exemplu, încercați să explicați mai întâi subiectul unui coleg.
• Scutește-te de sublinieri de toate felurile, de la caractere îngroșate la căsuțe de genul .[note].

Țineți minte aceste puncte pe tot parcursul scrierii dumneavoastră. Deprindeți-vă și cu sintaxa. Puteți utiliza un editor de prev izualizare pentru a previzualiza articolul pe măsură ce îl scrieți.

În plus față de punctele de mai sus, respectați și următoarele orientări:

• Engleza este limba principală, așa că modificările dvs. trebuie să fie în ambele limbi. Dacă limba engleză nu este punctul dumneavoastră forte, utilizați DeepL Translator, iar alții vă vor corecta textul.
• Respectați standardul de codificare din exemple.
• Scrieți numele variabilelor, claselor și metodelor în limba engleză.
• Spațiile de nume trebuie indicate la prima mențiune.
• Încercați să formatați codul astfel încât să nu fie afișate bare de defilare.
• Pentru documentație, consultați numai documentația sau www.

Contribuția la documentație

Trebuie să aveți un cont GitHub pentru a contribui la documentație. Puteți face modificări simple direct în interfața acesteia.

Cu toate acestea, este mai util să cunoașteți elementele de bază ale lucrului cu sistemul de versiuni Git. Dacă nu sunteți familiarizat cu Git, puteți consulta acest ghid rapid: git – the simple guide sau puteți utiliza unul dintre numeroasele instrumente grafice: GIT – clienți GUI.

Începeți să editați documentația prin crearea unui fork al depozitului nette/docs și clonarea acestuia pe computerul dumneavoastră. Apoi, efectuați modificări în ramura corespunzătoare, confirmați modificarea, împingeți-o în depozitul dvs. GitHub și trimiteți o cerere de tragere la depozitul original nette/docs.

Înainte de fiecare pull request, este o idee bună să rulați Code-Checker pentru a verifica dacă există spații suplimentare în text.

Structura documentației

Toată documentația este găzduită pe GitHub în depozitul nette/docs. Versiunea curentă se află în master, 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ă fiecare domeniu al 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ă versiunile lingvistice (cs, en, …) și, eventual, un subdosar files cu imagini care pot fi încorporate în paginile de documentație.