Propunere de workflow pentru modificarile aduse wiki-ului

[cipriancraciun]

Concluzie

TBD

Propunere

In esenta acest repository este exclusiv pentru feature-ul de "wiki". Ca urmare o prima varianta de "workflow" ar fi cea mai simpla: se editeaza pur si simplu paginile de wiki din interfata GitHub.

Totusi abordarea "simpla" are doua mari dezavantaje:

• nu exista posibilitatea de a marca clar continutul care este "publicat" (i.e. finalizat si recenzat) si continutul "draft";
• nu exista posibilitatea de a comenta asupra unui nou continut inainte ca acesta sa fie "publicat";

Evident putem utiliza markers de tipul "draft" / "ciorna" in continutul paginii, insa in felul acesta va trebui sa dublam numarul de pagini (o pagina "publicata" si una "draft").

Ca urmare propunerea este sa utilizam si repository-ul si wiki-ul in urmatoarea varianta:

• cine doreste sa modifice continutul va trebui sa isi faca un checkout al branch-ului master, unde va face modificarile dorite;
• apoi va trimite crea un pull request unde vor putea fi tinute discutii pe marginea celor publicate;
• in momentul in care este considerat "acceptat" (ramane de vazut cum se stabileste asta), continutul va fi merged in master;
• ca un pas final, noul master va fi impins in repo-ul de wiki.

Toate acestea implica durmatoarele Git repos:

• github.com/timisoara-business-venturers/knowledgebase.git -- unde este master branch-ul si in care se face pull request-ul;
• github.com/timisoara-business-venturers/knowledgebase.wiki.git -- unde este branch-ul pentru wiki; branch-ul acesta se numeste tot master, si acest repository nu apare in UI-ul GitHub, dar este legat cu repository-ul de baza;

[cipriancraciun]

Conform discutiei cu @mblaje ar trebui identificata o varianta de a permite usor unei persoane non-tehnice sa faca un review si sa modifice continutul documentului. (Spre exemplu via Google Docs.)

[cipriancraciun]

Pentru review cred ca am gasit solutia perfecta: DropBox Paper.

Functioneaza exact ca si Google Docs, anume este un editor de document colaborativ on-line.

Avantaje fata de Google Docs:

• import si export din MarkDown; (import-ul se face prin copy-paste, iar exportul fie tot asa copy-paste, fie prin o optiune speciala de export din meniu;)

Dezavantaje fata de Google Docs:

• nu suporta formatari arbitrare; (ceea ce poate este un avantaj;)

In rest suporta precum Google Docs urmatoarele:

• highlights;
• comments si replies;
• versions si comparison cu versiuni anterioare;

---

Ca urmare daca am folosi acest tool, workflow-ul pentru review ar fi cam asa:

• cream un nou document;
• dam import din MarkDown-ul nostru in Paper; (trebuie sa ne asiguram ca este compatibil cu cel uploaded;)
• dam un export din Paper, pentru a avea varianta de baseline; (in esenta ar trebui sa fie identic cu importul, insa pot aparea diferente ca urmare a procesarii de Paper;)
• se parcurge in mod normal procesul de review pe text cu comentarii si modificari;
• se da export din Paper;
• se face diff fata de ce avem noi ca baseline;
• diff-ul ce rezulta ar putea fi aplicat de noi manual pe documentul actual pe care il avem;

In esenta fazele de editare al unui document, in care se integreaza si review-ul ar fi:

• editare initiala in MarkDown si share via GitHub intr-un branch draft/topic;
• review initial de catre noi via GitHub pull requests;
• review efectiv de catre avocat / expert via DropBox Paper;
• merge modificari in GitHub si update la pull-request; (se intampla tot pe draft/topic;)
• merge pull-request in master;
• push master din repo in master in wiki;

[mblaje]

Dude, eu sunt incantat de aceasta solutie chiar daca nu e perfecta.

1. Ne costa ceva Dropbox Paper?
2. Poti face o inregistrare tip tutorial despre cum pot persoanele non-tehnice sa ceara acces si sa faca modificari / colaborari pe un topic? Cred ca ar fi util pentru ei un filmulet de 1-2 min despre flow-ul pe partea lor.

[cipriancraciun]

1. Ne costa ceva Dropbox Paper?

Nu, este gratis, trebuie doar sa ai cont de DropBox.

2. Poti face o inregistrare tip tutorial despre cum pot persoanele non-tehnice sa ceara acces si sa faca modificari / colaborari pe un topic? Cred ca ar fi util pentru ei un filmulet de 1-2 min despre flow-ul pe partea lor.

O sa ma gandesc la partea asta. Voi face asta inainte de primul review, o data ce stim exact si cum e structurat documentul si cum integram totul in workflow "pe viu". (Momentan experimentam cu workflow-ul.)