Propunere structurare pagini de wiki

cipriancraciun commented 4 years ago

Sumar

Pentru a mentine un nivel de calitate si trasabilitate al continutului publicat in wiki, consider ca ar trebui sa identificam cateva "reguli" de organizare a fiecarui document in sine.

Concluzie

TBD

cipriancraciun commented 4 years ago

(Voi scrie propunerea in comments, pentru a pastra "body-ul" issue-ului de mai sus pentru concluzii.)

Pe scurt cred ca ar trebui sa structuram fiecare document precum un "articol stiintific" (desi poate nu atat de riguros), sau poate mai aproape de cum sunt structurate articolele pe WIkipedia.

Mai jos incerc sa sumarizez cateva propuneri.

Denumirea documentelor

Din nefericire wiki-ul de la GitHub are cateva limitari:

desi putem stoca fisierele intr-o ierarhie de directoare, aceste directoare nu vor fi vizibile in wiki;
numele fisierelor sunt preluate si transformate direct in titluri de pagina;
caracterul - este considerat "spatiu" in aceasta transformare;

Ca urmare as propune sa structuram numele fisierelor (si astfel a titlurilor) astfel:

pentru fiecare articol putem identifica o structura ierarhica de tipul "categorie" / "topic", precum Declaratie unica / Venituri din investitii si dividende;
numele fisierului este obtinut prin concatenarea acestor tokens cu ~~ (i.e. "spatiu", "tilda", "tilda", "spatiu") si inlocuirea spatiilor cu -, anume Declaratia-unica-~~-Venituri-din-investitii-si-dividende.md;

Documente "de sine statatoare"

Fiecare document ar trebui sa fie "self-contained" pentru topic-ul pe care il descrie. Este OK sa referentieze alte documente (pentru concepte generale sau legate), insa tot ce este strict legat de acest topic ar trebui sa fie prezent in document.

Structura interna a documentului

In esenta fiecare document ar trebui sa aiba minim 4 sectii, identificate cu heading-urile:

## Sumar
## Meta
## <Sub-topic-1>
## <Sub-topic-2>
## Bibliografie

Unde Sumar ar trebui sa contina o scurta descriere (chiar concluzie) a celor descrise.

Bibliografie ar trebui sa contina link-uri catre pagini sau referinte de lege care sa sustina cele descrise in document.

Si cel mai important Meta care ar trebui sa includa urmatoarele:

status -- vezi mai jos;
autori / autori -- care efectiv au creat documentul;
recenzor / recenzori -- care au citit si "aprobat" documetul; (in esenta se realizeaza pe baza de pull-request;)
actualizat -- cat a fost ultima data actualizat in mod major documentul; (in esenta informatia se regaseste deja in commit-urile paginii;)

Status-ul ar trebui sa indice clar urmatoarele:

daca continutul acestui document inca se mai aplica; (poate legislatia a fost modificata sau abrogata intre timp;)
cand a fost verificat ultima data daca continulu mai este inca aplicabil;
cine a facut aceasta verificare;

In esenta acest camp ar putea avea doua valori urmat de data la care a fost modificat, spre exemplu:

valid 2020-05-04 (Ciprian) -- semnifica ca in data de 2020-05-04 a fost verificat ca inca mai este valabil;
neaplicabil incepand din 2020-05-09 -- data de la care nu a mai fost considerat aplicabil;
aplicabil incepand din 2020-05-10 -- data de cand ar urma sa fie valabil;

Toate aceste campuri ar putea fi liste (autori, recenzori, etc.) si in special status care ar trebui sa tina un jurnal.

In principiu daca putem cadea de comun acord cu cele de mai sus, am putea crea si un template de document.

cipriancraciun commented 4 years ago

Impreuna cu @mblaje si @andreeapitici am ajuns la urmatoarele concluzii:

in paginile de wiki vom avea sectiuni diferite dedicate SRL/PFA;
in repo vom avea un folder ce trateaza un anumit topic (spre exemplu Declaratia unica;)
cele doua ierarhii (wiki sections si links) si repo (folders si files) sunt independente;

De asemenea, chiar daca fiecare document ar trebui sa fie self-contained si use-case specific, cand vom avea cazuri in care diferentele intre use-case-uri sunt mici, le putem pune intr-un document comun.

timisoara-business-venturers / knowledgebase