Aprašymo gyvenamoji vieta

[grinkus]

Kur tie aprašymai turėtų gyventi? Dabar matau kelis variantus:

• Wiki
  • Bėda ta, kad projektas gali turėti nuosavą wiki ir taip, kur proceso aprašymui vietos gal ne visai ir yra. Nebent tai būtų vienas page'as, su nuosavais subpage'ais (ar tai leidžia gh wiki?), arba subsekcijom (su anchor'ais).
• Nuosavas branch'as (e.g. darau-aprasymas)
  • Iš jo front-end'as pullintų md failus ir juos rodytų – taip nereiktų simuliuoti gh-pages funkcionalumo.
• Gist
  • Tokiu atveju įrašas gali būti komentuojamas (per GitHub web GUI ir per darau web intefeisą)
  • Netgi gali būti redaguojamas kelių žmonių. Nors GitHub web GUI neturi galimybės lengvai pull'inti svetimo gist fork'o, tai padaryti būtų galima klientu, nes gist turi savo atskirą repozitoriją (kaip ir wiki). Būtų gerai išsiaiškinti ar tai pasiekiama naudojant GitHub octokit (api client lib'ą)?
  • ! Gist negali priklausyti projektui. Gist'ai priklauso tiesiogiai user account'ui. Panašu, kad variantas atkrenta.

[grinkus]

Dar tai gali būti nuosava repozitorija po user'io arba organizacijos account'u. Variantas įdomus dėl to, kad ji galėtų turėti nuosavą issues seką, nuosavą wiki, ir, kas įdomiausia, nuosavą gh-pages branch'ą. Būtų prieinamas po makerspace.lt/aprasymas-projektas (kaip pavyzdys) ir gali būti stilistiškai skirtingas nuo visų kitų projektų (turint savo stylesheet'ą, kurį galėtų judinti žmonės, kurie draugauja su git repozitorijom (ateityje tai galėtų handle'inti „Darau“, bet kol kas nesikarščiuokim)).

[grinkus]

Atskiros repozitorijos mintis ne visai protinga – visgi projekto proceso aprašymas semantiškai yra projekto dalis. Paieškojus galima rasti projektų su kiek nuodugniau sutvarkytais wiki: Netflix/Hystrix, mcMMO, Snowplow, Boris-Em/BEMSimpleLineGraph.

Masčiau ir apie aprašymo laikymą gh-pages, bet čia atsiranda labai keistų kintamųjų:

• saitas jau gali būti veikiantis ir naudojamas,
• niekas nežino kaip jis markup'inamas ir kaip jis veikia,
• būtų gerai naudoti kokį nors WYSIWYG redaktorių, bet tada kyla amžina ir neišsprendžiama problema kaip priversti vartotoją suprasti skirtumą tarp semantinio markup'o ir stiliaus.

Žodžiu, kol kas wiki man atrodo protingiausias sprendimas, ypač kai matom, kad jis gali būti kelių level'ių.