Skip to content

Home

Jump to bottom
Razvan Deaconescu edited this page Oct 31, 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.

Să evităm folosirea "ei / ele / el / ea" pentru subiecte non-umane. Preferăm folosirea "aceștia / acestea / acesta / aceasta". La fel, în loc de "lui / ei / lor", preferăm "său / sa / sale".

Î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 exerciț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 sute ș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 (tutoriale, 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.

Structurarea și exprimarea conținutului

Folosim principiul less is more. Nu dezvoltăm ideile mai mult decât este cazul, intrăm cât mai repede în pâine, la exemple concrete de folosire a unei aplicații GUI sau a unui utilitar CLI. O (sub)secțiune va fi cuprinsă din:

  1. prezentare succintă a conceptului, nevoii, problemei
  2. un sumar al obiectivului secțiunii, ce va fi prezentat în secțiune care duce la înțelegerea conceptului sau rezolvarea problemei
  3. tutoriale și exemple concrete de folosire a aplicațiilor / utilitarelor
  4. exerciții cu aplicațiile / utilitarele de mai sus; exercițiile pot fi presărate printre exemple, nu trebuie să fie la final
  5. un eventual sumar de comenzi, bune practici

La începutul unei (sub)secțiuni vom prezenta, în cât mai puține cuvinte, nevoia, problema, motivul, contextul. Răspundem la întrebări care încep cu "De ce?": "De ce e important să știm asta?", "De ce există această problemă?", "De ce dorim să o rezolvăm?", "De ce dorim să facem așa și nu altfel?", "De ce se întâmplă lucrurile așa și nu altfel?". După prezentarea contextului vom prezenta, din nou în cât mai puține cuvinte, obiectivul, unde vom ajunge, vom da răspunsul la întrebarea "Unde vrem să ajungem în această secțiune?" ("Ce vrem să atingem?"). Obiectivul este, evident, derivat din context / nevoie. Prezentăm nevoia / contextul și obiectivul prin situații concrete, reale / realiste; nu la modul "asta poate fi util, vedeți voi unde".

În (sub)secțiunile care prezintă un scenariu care cuprinde mai mulți pași care se vor întinde pe mai multe subsecțiuni, facem la început o sumarizare a pașilor. Ca să fie clar cititorului ce va face, pe ce drum va merge. Să nu fie surprins cititorul când întâlnește un pas și să nu-l lege de "the bigger picture".

Tutorialele și exemplele sunt partea centrală a (sub)secțiunii. Exprimarea va fi la persoana I plural ("edităm", "creăm", "parcurgem", "instalăm"), însemnând că cititorul este "dus de mânuță" prin fiecare tutorial și exemplu și trebuie să execute pașii de acolo. Orice concept sau nevoie sau comandă introdusă trebuie să aibă tutoriale și exemple de utilizare.

Exemplele, la fel ca exercițiile, vor prezenta situații realiste de utilizare a aplicațiilor / comenzilor. Dacă nu se poate altfel, spunem explicit că acest exemplu / exercițiu este didactic, pentru că o situație realistă este complicat de înțeles sau simulat.

Atunci când se prezintă o situație într-un exemplu, tutorial, mergem de la specific la general, de la concret la abstract. Întâi prezentăm un exemplu efectiv de folosire a unei aplicații sau a unui utilitar apoi prezentăm pe larg conceptul din spate. Ca cititorul să fi rulat ceva, să fi văzut ceva concret, să aibă ceva de care să se lege. Adică, în cazul unui exemplu / tutorial, vom urma secvența:

  1. spunem ce vrem să facem
  2. prezentăm aplicația / comanda cu care facem
  3. detaliem ce am făcut, de ce este acesta modul de folosire, care sunt alte moduri

Adică spunem: "Ca să facem X, rulăm comanda Y ca mai jos: ... exemplu-efectiv-de-rulare-comanda ... În outputul de mai sus ..."

Nu prezentăm sintaxă de comenzi sau aspecte de anatomie (cum este construită o aplicație, ce se întâmplă în spate) decât dacă acest lucru este util cititorului pentru a înțelege nevoia / conceptul. Sintaxa este documentată în documentația oficială (manual, Internet), nu o prezentăm noi. Noi insistăm pe exemple reale / realiste și pe scenarii concrete de folosire a aplicațiilor / comenzilor.

Dacă o (sub)secțiune prezintă un scenariu cu mai mulți pași, care au fost detaliat exemplificați, atunci va mai fi un exemplu ("dus de mânuță") în care se va trece pe repede înainte prin aceeași pași, acum deja cunoscuți, pentru a asigura înțelegerea lor.

Exercițiile sunt pentru aprofundarea conceptelor și bunelor practici din exemple. Primul/Primele exerciții din partea de exerciții trebuie să fie repetări ale exemplelor; adică faci ce ai făcut și în exemplu (cu alți parametri), dar de unul singur. Repetări ale exemplelor înseamnă că nu există nici un nivel suplimentar de dificultate, nici un parametru sau variabilă nouă a scenariului; este scenariu identic, dar cu alte valori ale variabilelor / parametrilor scenariului. După primul / primele exerciții de repetare, pot fi și exerciții cu care aduc parametri / variabile noi în scenariu. La exerciții folosim persoana a II-a plural ("editați", "creați", "parcurgeți", "instalați").

În exemple, tutoriale și exerciții folosim nume realiste pentru fișiere, arhive, repository-uri, utilizatori. Nu folosim nume precum "my-file.txt", "test-user" sau "first-repo".

Atunci când este nevoie de explicații suplimentare sau clarificări folosim note (note, warning, important, admonition) sau folosim note de subsol (footnotes). Dacă explicațiile ar rupe din fluxul curent și / sau nu sunt atât de relevante pentru cititor, le trecem ca note de subsol. Dacă explicațiile sunt atunci utile cititorului, le trecem ca note. Dacă sunt utile dar nu atunci, le putem trece într-o (sub)secțiune de bune practici sau "Alte scenarii" sau "Extra" la final.

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