Skip to content

Home

Jump to bottom
Razvan Deaconescu edited this page Sep 19, 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. O secțiune cuprinde un subiect al laboratorului.
  • celelalte (subsections, subsubsections, paragraphs) vin după cum e nevoie. 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 individual, fără a fi "ținut de mânuță": "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.

Nu facem în editor limitarea numărului de caractere ale unei linii. Fiecare propoziție va fi scrisă în editor pe o linie nouă. În felul acesta, orice modificare a unei propoziții va afecta o singură linie din fișierul sursă, nu mai multe linii / un paragraf.

Subsecțiunile (-----) le vom numerota cu numere urmate de punct. De exemplu: 1. Pornirea unei aplicații, 2. Repornirea unei aplicații, 3. Închiderea unei aplicații. Subsubsecțiunile (^^^^^) le vom numerota cu litere urmate de punct. De exemplu a. Pornirea unei aplicații în mediul grafic, b. Pornirea unei aplicații în linia de comandă, c. Pornirea unei aplicații în background. Nu numerotăm secțiunile (=====) sau paragrafele (""""").

De principiu folosim subsecțiuni pentru a agrega activități (tutoariale, exerciții, întrebări) din același registru și subsubsecțiuni pentru fiecare idee de activitate. Dacă obiectivul de activitate are mai multe subpuncte, se pot folosi paragrafe.

Două exemple de formatare:

  1. Secțiunea Rularea aplicațiilor are subsecțiunea 1. Aplicații și procese care agregă activități care se referă la procese. Subsubsecțiunea b. Afișarea proceselor după anumite atribute este activitatea efectivă. Aceasta este cuprinsă dintr-un scurt breviar despre atributele unui proces, un tutorial / demo și două exerciții (de făcut de cititor). Exercițiile se găsesc în paragrafele Selectarea proceselor după procesul părinte și Selectarea proceselor care aparțin unui utilizator.
  2. Secțiunea Folosirea eficientă a browserului are subsecțiunea 1. Scurtături de tastatură care agregă activități care se referă la scurtături de tastatură în folosirea browserului. Subsubsecțiunea c. Navigarea taburilor deschise este activitatea efectivă. Aceasta conține tutoriale de navigare între taburi diferite ale browserului. Nefiind exerciții, subsecțiunea nu conține paragrafe.

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

Pentru primii pași și bune practici în Git, recomandăm:

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/

E opțională folosirea opțiunii -s / --signoff când facem un commit.

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.

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

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

În mod obișnuit commiturile din fiecare pull request vor fi comasate (squashed) într-un singur commit. Folosim rebase pentru pull requesturi, nu merge, ca să avem o "linie" de commituri, fără commituri de merge (merge commits).

Clone this wiki locally