Průběh prací

Upozornění: Tohle vlákno je hodně staré a informace nemusí být platné pro současné Nette.
Inza
Člen | 330
+
0
-

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:

  1. 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.
  2. Mezitím s Davidem doladíme jak bude poté probíhat comit/deployment a storing verzí doku a potom to sem napíšu.
  3. 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:

  1. Vleze sem na fórum.
  2. 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.
  3. Začne na tom pracovat. Když má kus hotov, comitne to (postup „comitování“ bude upřesněn).
  4. Zapíše to že to comitnul do Milníků (Milestones)
  5. Kontroluje Dokumentace – Feature Requests a Repair Requests, zda se to všem líbí, pokud jsou nějaké námitky, skok na bod 3.
  6. 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
+
0
-

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
+
0
-

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
+
0
-

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
+
0
-

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
+
0
-

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