-
Notifications
You must be signed in to change notification settings - Fork 4
Home
Folosim resursele de mai jos ca documentare pentru Restructured Test și ghiduri de scriere a conținutului:
- [1]: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html
- [2]: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
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.
Pentru dezvoltarea conținutului, avem informații din echipa "Lab Mentors" din 2013:
- https://docs.google.com/document/d/1ZZXVbW_hfGlFoU8IjtI_qNAdovDZ6bAPh0mpy_40s1k/edit?usp=sharing
- https://ocw.cs.pub.ro/courses/mentors/template
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".
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:
- 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ă.
- Când finala se pronunță diferit în limba română. Show (șou). DOOM recomandă articularea cu cratimă: show-uri. Simplu.
- 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. Dar show-ul, Bruxelles-ul, hobby-ul.
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 prectici de folosire Git: https://techblog.rosedu.org/git-good-practices.html