Dokumentace: repo vs. wiki rubrika: Programování: Jiné
2
borekb
Píšete dokumentaci do repa, např. složky docs, nebo do wiki či podobného externího systému?
Co se mi líbí na repu:
- Dokumentace je verzovaná spolu s kódem - tedy aspoň technicky (že někdo neupraví README.md a dokumentace se tak rozsynchronizuje s kódem, je jiný problém). Je to asi jediný důvod pro, ale z mého pohledu dost silný.
Co se mi líbí na wiki či podobném dokumentačním systému:
- Je obecně přístupnější - kliknout někde na "edit" a prostě udělat úpravu je jednodušší než manipulovat se soubory v repu.
- Osobně u wiki automaticky opravuju kdejaký překlep, zatímco u repa mám tendenci přemýšlet, jestli to za ten commit stojí (a jestli ho dělat do aktuální feature branche, případně se prudit s přepínám do masteru, a co když máme politiku "nikdy necommitovat do masteru" apod. - prostě je to trošku bariéra pro rychlý fix)
- Obrázky či jiné velké binární soubory tam lze frkat bez velkého přemýšlení, jestli tím nezatížím hlavní repo
Na wiki se mi obecně nelíbí, že má tendenci se rozsynchronizovat se stavem repa - v praxi se bohužel děje, i když se snažíme vše udržovat aktuální. Rovněž, pokud je několik verzí projektu, musí být wiki napsaná pro všechny verze, ale s tím zas takový problém nemám - i naši veřejnou dokumentaci udržujeme pro více verzí pomocí "feature togglů" a připadá mi to lepší než mít samostatnou branch pro každou verzi dokumentace.
--
Aktuálně to ve VersionPressu většinou děláme tak, že v repu jsou drobné dokumentace k jednotlivým technickým aspektům (např. nějaké README pro malý, samostatný subsystém) a věci typu setup prostředí nebo typický obsah CONTRIBUTING.md dáváme do wiki. Jak to děláte vy?
1
hrachcz
U open-source Nextras component davam dokumentaci do repa, vidim v tom nekolik vyhod:
- vice verzi dokumentace dle kodu,
- mentalni blok - commituju az s doc (ala commituju s testy),
- mene rezie - jedno repo, jeden push, jedno okno konzole, ...
Argumenty, ze je skoda commitu - nevim, neprijde mi to prislis velky problem. Edit na githubu je taky. Ja osobne pouzivam texy, takze je to bez nahledu, ale s markdownem mas i nahled. Na wiki velke binarni soubory nemaji co delat. Ze je obrazek v repu je spravne. Muze te to taky motivovat vic k SVG, etc. Navic, je tu Git LFS.
Komentáře
-
borekb
:
Počítáš za "dokumentaci" i jak zprovoznit vývojové prostředí, např? Máš všechno striktně v repu a vůbec nic mimo?
—
18.1.2016
-
hrachcz
:
Ano, pocitam. Napr. u Nextras Dbalu mam i neco jako "Tutorials", ktery prave obsahuje info, jak neco zprovoznit.
—
23.1.2016
Pro zobrazení všech 7 odpovědí se prosím přihlaste:
Nebo se přihlaste jménem a heslem:
Komentáře