Skip to content

Home

Jump to bottom
Razvan Deaconescu edited this page Aug 4, 2020 · 19 revisions

Ghid de scriere

Sintaxa reStructuredText (reST)

Folosim resursele de mai jos ca documentare pentru Restructured Test și ghiduri de scriere a conținutului:

Pentru headinguri, așa e descris și în documentație ([1], [2]), folosim:

  • parts (#####): nu avem ceva clar, probabil partea 1 pentru utilizatori obișnuiți și partea 2 pentru utilizatori administrativi. Dar aș lăsa-o deoparte, deci pe moment nu avem nimic cu ##### (deasupra și dedesubt).
  • chapters (*****): fiecare laborator este un capitol, fiecare dintre noi lucrează acum la un capitol. Pe moment, nu avem un fișier destinat unui capitol în care să includem apoi secțiunile acestuia. Poate va fi cazul. Dar pe moment nu avem nimic cu ***** (deasupra și dedesubt).
  • sections (=====): fiecare fișier pe care l-am făcut noi cu secțiuni va intra aici. Este, în forma curentă de implementare, cel mai top-level nivel de indentare. Se pune doar dedesubt.
  • celelalte (subsections, subsubsections, paragraphs) vin după cum e nevoie. Aș pune fiecare exercițiu / activitate (poate fi tutorial, breviar) ca subsection și dacă are subpuncte subsubsection. Nu văd pe moment unde ar intra paragraph; poate la un subpunct vrem să separăm anumite idei. Se pun doar dedesubt.

Scrierea și formatarea conținutului

Pentru dezvoltarea conținutului, avem informații din echipa "Lab Mentors" din 2013:

Să începem cu formă de substantiv din verb articulat titlurile exercițiilor "Instalarea unei aplicații" "Compilarea unui program".

Să evităm folosirea bulleturilor. Să fie literale (fraze, paragrafe) enunțurile și explicațiile exercițiilor.

Începem o activitate cu descrierea obiectivului. Să fie clar cititorului la ce este utilă activitatea, unde vrem să ajungem.

Folosim persoana 1 plural pentru tutoriale și activități care intră în categoria "ținut de mânuță": "descărcam aplicația", "testăm conectivitatea", "compilăm programul". Folosim persoana a 2-a plural pentru exercții și activități care trebuie să fie făcute de cititor: "instalați aplicați", "realizați conectivitatea", "compilați programul".

Pentru numerale, folosim forma literală doi, trei, patru, cinci în loc de 2, 3, 4, 5 pentru numere de o singură cifră și forma numerică pentru numere de două sau mai multe cifre: 10, 69, 666, 8080 în loc de zece, șaizeci și nouă, șase suste șaizeci și șase, opt mii optzeci.

Limba română și limba engleză

Nu suntem absurzi în folosirea limbii române. Acolo unde nu avem un echivalent, sau avem un echivalent forțat, folosim limba română. Folosim wireless, firewall, target, repository, commit, pull request, branch, browser, nu folosim zid de foc, depozit, cerere de tragere, ramură, navigator sau alte minuni. Acolo unde se poate folosim limba română: putem folosi fără fir în loc de wireless, dar aș lăsa loc pentru ambele; la fel nucleu și kernel. Dar compilator, nu compiler, regulă nu rule, adresă IP nu IP address, client web nu web client.

Pentru articularea cuvintelor venite din limba engleză, buffer-ul sau bufferul, folosim regulile următoare:

  1. Când finala, ultima literă a englezismului, se pronunță ca în limba română (e-mail, board). DOOM recomandă articularea fără cratimă (e-mailul, boardul). Experiență arată că s-ar putea ivi probleme, de exemplu între "boarduri" (înțelese ca organisme de conducere, consiliul director) și "borduri". Dacă s-ar fi scris la fel, dar se citeau diferit datorită accentului erau omografe (copii / copii, acele și acele), însă așa constituie doar o altă problemă.
  2. Când finala se pronunță diferit în limba română. Show (șou). DOOM recomandă articularea cu cratimă: show-uri. Simplu.
  3. Dacă cei doi termeni se se scriu și de citesc identic (blog, spam, link, stick), articularea englezismului se face fără cratimă. Blogul, spamul, linkul, stickul. Nu există nici un motiv să fie altfel.

Deci bufferul, serverul, targetul, Internetul, linkul, Washingtonul, headingul, bulletul, commitul. Dar show-ul, Bruxelles-ul, hobby-ul, branch-ul.

Pentru folosirea diacriticelor, recomandăm folosirea layoutul de tastatură "Romanian (Programmers)". Atenție la folosirea diacriticelor de tip comma-below, nu cedilla-below, așa cum e indicat aici. Detalii despre diacritice și configurarea și folosirea lor: https://ro.wikipedia.org/wiki/Wikipedia:Diacritice

Ghid de folosire Git / GitHub

Nu facem commit în branch-ul master. Facem un branch separat, facem commituri acolo și apoi creăm pull request. După ce pull requestul este recenzat, se face merge în branch-ul master.

Pentru fiecare pull request vor fi (cel puțin) doi recenzori.

Folosim GitHub flow (branch, pull request, merge) pentru adăugarea de conținut prin Git / GitHub: https://guides.github.com/introduction/flow/

Modelul colaborativ GitHub detaliat (issues, pull request): https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests

Scriem mesajele de commit în limba engleză.

Mesajele din pull request-uri le scriem în limba în care este scris conținutul. Dacă este conținut în limba română, mesajele de pull request vor fi în limba română.

Pentru a scrie mesaje bun de commit în Git: https://chris.beams.io/posts/git-commit/

Pentru bune practici de folosire Git: https://techblog.rosedu.org/git-good-practices.html

Clone this wiki locally