Průběh prací
- Inza
- Člen | 330
Tak, můj prvotní návrh na průběh prací je následující:
Každá ze plánovaných 4 částí dokumentace Nette (více viz. Slovo úvodem) má nyní své dedikované vlákýnko, kde se bude probírat.
postupovat navrhuji takto:
- Několik dní zkonzultovat, co komu na které části doku vadí, popř. co by si o které představoval (není třeba říkat co již bylo řečeno) – tak nějak bych si představoval že by se tyto názory objevily ve vláknech jednotlivých doku.
- Mezitím s Davidem doladíme jak bude poté probíhat comit/deployment a storing verzí doku a potom to sem napíšu.
- O té chvíle budeme moci pracovat na změně doku k lepšímu. Založím ještě vlákýnko na rozdělení prací, kam můžete psát: „beru si na starost tohleto, bude to odhadem tehdy a tehdy…“. Také udělám vlákno Milestones, kam budeme šoupat oznámení typu: „tak jsem comitnul doku k tomuto, čekněte to a když byste měli nějaké výhrady, tak sem s nimi“ – ty výhrady se už ale nebudou šoupat do těch milestonů, nýbrž do dedikovaných vláken…
No uchazeč tvorbu dokumentace tedy bude postupovat podle tohoto algoritmu:
- Vleze sem na fórum.
- Chce napsat doku např. k Nette/String – v PRG. Vleze do Rozdělení prací a zkontroluje, zda už na tom nedělá někdo jiný, pokud ano, domluví se s ním. Pokud ne, zapíše, že chce měnit tohleto a bude to přibližně tehdy a tehdy.
- Začne na tom pracovat. Když má kus hotov, comitne to (postup „comitování“ bude upřesněn).
- Zapíše to že to comitnul do Milníků (Milestones)
- Kontroluje Dokumentace – Feature Requests a Repair Requests, zda se to všem líbí, pokud jsou nějaké námitky, skok na bod 3.
- Kýžená část doku je hotová, autor je spokojen. Má-li zájem může udělat skok na 1 a vybrat si další část doku k refaktoringu…
Tak taková je má idea… co vy na to? Davide?
Editoval Inza (13. 4. 2009 15:19)
- David Grudl
- Nette Core | 8284
Jelikož celý web je postaven jako wiki, commit/deployment je vyřešen – prostě každou stránku lze editovat a hned uložit.
Mohla by se vytvořit stránka Documentation Roadmap, kde by se dalo
sledovat, jaké stránky jsou hotové (rozpracované stránky je také možné
označovat nějakým tagem, např {{working}}
). K pravidlům pro
psaní dokumentace slouží stránka Wiki
syntaxe.
Během přípravných prací možná dojde k větším zásahům, které by
nebylo vhodné hned zobrazovat v ostré dokumentaci, proto jsem nahodil
XX verzi https://nette.org/xx/dokumentace
. Je to
speciální jazyková verze, kde se všechny stránky přebírají ze současné
cs verze, dokud je nezměníte a neuložíte. V XX tedy lze připravit návrh
nové struktury a pak bych ji překlopil do CS.
Logická struktura je asi docela vymyšlená, otázkou zůstává struktura URL adres. Navrhoval bych
/quickstart/... pro jednotlivé kapitoly Quick Startu
/guide/... pro celou The Definitive Guide
/screencasts/... pro budoucí screencasty, Cookbook a tutorialy
/cookbook/...
/tutorials/...
/extras/... Repozitář komponent a pluginů (už existuje)
Programmer's Reference Guide by mohl teoreticky zůstat v rootu (tj. v
https://nette.org/cs/...
), protože každá stránka stejně
začíná prefixem nette...
.
- Inza
- Člen | 330
Nahození XX verze je úplně super nápad – přesně to jsme potřebovali, tu roadmapu udělám dneska – asi večer.
Jinak k těm URL, navrhuji ještě i alternativně (jednosměrky):
- /qs/ – Quick Start
- /tdg/ – The Definitive Guide
- /prg/ – Programmers Reference Guide
- /api/ – API
Jde o to, aby to bylo unifikované – a také mít stránku, kde budou odkazy na všechyny výše uvedené (a ještě výše davidem uvedené)… – tu stránku vytvořím.
Jinak to, zda je dobré mít i alternativní unifikované URL, je k diskusi…
Možná alternativní nedělat, jen udělat unifikaci – a i Reference guide dát do /reference-manual/ nebo tak něco a na Homepage by byl obsah dokumetace – neboli linky na 4 části, případně i ty další.
Nebo to nějak poladit modifikací designu mít podmenu – se všemi částmi…
Jde mi o to, abychom nevyzdvihovali PRG…protože potom user, co nic neví a chce najít OS ho při kliknutí na DOKUMENTACE na webu nette nenajde – je to k diskusi – jaký je váš názor?
- Jan Tvrdík
- Nette guru | 2595
David Grudl napsal(a):
(…), proto jsem nahodil XX verzi
https://nette.org/xx/dokumentace
. Je to speciální jazyková verze, kde se všechny stránky přebírají ze současné cs verze, dokud je nezměníte a neuložíte.
Tak to jsem buď nepochopil, nebo to nefunguje. Čekal jsem, že na adrese https://nette.org/xx/quick-start se zobrazí to, co na adrese https://doc.nette.org/cs/quickstart dokud tu stránku někdo neupraví.
- Inza
- Člen | 330
Jan Tvrdík napsal(a):
Tak to jsem buď nepochopil, nebo to nefunguje. Čekal jsem, že na adrese https://nette.org/xx/quick-start se zobrazí to, co na adrese https://doc.nette.org/cs/quickstart dokud tu stránku někdo neupraví.
Ne ne, nepochopil jsi to;-) – David zkopíroval jen tu úvodní stránku – tu jsem přesunul do /old/ – to je dobře že se to nezobrazí – jinak bychom pořádně neměli přehled co jsme už udělali a co ještě ne…
- modrý odkaz = je to ok, stránka existuje
- červený odkaz = neexistuje
Možná že to david myslel skutečně tak, jako ty, ale takhle je to lepší…
- David Grudl
- Nette Core | 8284
Jan Tvrdík napsal(a):
Tak to jsem buď nepochopil, nebo to nefunguje. Čekal jsem, že na adrese https://nette.org/xx/quick-start se zobrazí to, co na adrese https://doc.nette.org/cs/quickstart dokud tu stránku někdo neupraví.
Opravím to