Nette Documentation Weekend – #0 – Pokus

Je to dobry napad, hlavne s tym BaseCamp-om, ale slovaci tento vikend odpadavaju, su u nas volby :)

Mohu doporucit jako nej nastroj, kdyz ma vice lidi psat jedno urcite Google Wave. Pouzivame to v praci na psani dokumentaci a specifikaci k projektum.

Osobni setkani by asi bylo lepsi. Klidne by se mohlo udelat vic teamu. Treba HK, PCE a okoli se sejit nekde, PHA nekde atd. Bylo by to asi optimalnejsi nez zabit cely den cestovanim.

Co mam zkusenosti se Skype a spol tak pokud to nevede pevna ruka tak se tam bordel.

Jelikož to bylo celkem na rychlo. Tak nás moc není takže by se toho nedalo moc zrealizovat. Takže tento víkend nebudeme věnovat samotnému psaní dokumentace. Ale budeme vymýšlet přesnější plán pro víkend příští aneb jak to celé přesně bude fungovat.

Pokud se chcete do této diskuse zapojit tak můžete zítra na Nette Jabber roomu kolem 14hod. Výsledek pak hodíme někam na wiki.

Ad řešit to v hospodě. Plán je takový že tuhle „akci“ budeme dělat jednou za 14dní. Tj 2× měsíčně. Chtěl bych to udělat tak aby jeden z těchto 2 víkendů vycházel na Poslední Sobotu. Takže budeme mít jednou měsíčně off-line NDW a jednou měsíčně on-line NDW.

Souhrn Prvního dne

• Shodli jsme se, že dokumentaci budeme psát „kompletní“ (jako jQuery) a případné tutoriály budou lidé psát na Wiki
• Našli jsme pár nesrozumitelných věcí na https://wiki.nette.org/cs/syntax
• Potřebovali bychom vědět, jak je to s TAGováním „článků/kapitol“ – prý to zatím není dodělané
• Shodli jsme se, že stávající a navrhovaná struktura dokumentace je moc závislá na namespace
  • a tak jsme dali do kupy novou strukturu dokumentace https://dev.nette.org/…-dokumentace 
• Dohodli jsme se, že budeme psát dokumentaci pro 1.0-alpha (potažmo dev) předpokládáme vydání 1.0 jako stable před/zároveň s dokončením dokumentace
• shodli jsme se, že ideální způsob psaní je
  1. Napsat
  2. Nechat někým druhým zkontrolovat
  3. Finální oprava/kontrola (autorem)
• ač je doporučováno psát dokumentaci anglicky, panuje názor že by se nejdříve měla dokončit česká dokumentace a pak teprve začít překládat (aby byla alespoň jedna verze „kompletní“)
  • dalo by se to řešit i takto (v návaznosti na předchozí postup)
    4. Článek/Kapitola je finální a tak se přeloží (nemusí to nutně dělat autor české verze)
    5. Korekce někým dalším (myšleno někým jiným než je překladatel)
    6. Finální oprava/kontrola (překladatelem) ne nutně i autorem
  • kroky 3 a 6 nejsou nezbytné
• hodil by se nám styl dev-feature nebo něco podobného (něco jako je dosavadní tip/caution/warning pro absolutní novinky)
• shodli jsme se, že samostatné použití šablon, formulářů a ostatních přesuneme někam mimo a budeme na to pouze odkazovat (chce to promyslet, jestli neudělat výjimku, aby se to mohlo hodit na wiki)
• po několikáte jsem vysvětlil, jak to je s dělením dokumentace podle verzí nette
  • Dokumentace se píše pro verzi 1.0, až bude pro verzi 1.0 a přijde nová verze Nette, bude se tohle řešit. Teď to nemá smysl.

Celkem se nás sešlo 10. Většina těchto informací se dohodla na Google Wave, ostatní na Nette Jabberu

OT: chvílemi bylo doopravdy zajímavé, jak všichni najednou řešíme v jednom „postu“ strukturu dokumentace, zároveň se ptáme, proč tohle tak a tak a ne jinak. Za sebe musím říct, že se Google Wave osvědčil(a).

Co nás čeká dnes?

• Dát dohromady kompletní návod, jak psát dokumentaci
• Projít stávající dokumentaci a doplnit issues o komentáře, zda je daná věc hotová / zda potřebuje aktualizaci / zda schází
• Můžeme začít psát

Druhý bod můžete začít řešit v podstatě ihned, další začneme řešit kolem 15–16hod. Dnešní wave: http://jdem.cz/fhy98

Editoval vrtak-cz (13. 6. 2010 9:06)

Jan Tvrdík napsal(a):

Čekal jsem, že je opravíte a ono nic :)

Chtěl jsem ale už jsem to nestihl a neměl jsem na to sílu… (Po probdělé noci jsem šel spát v 9ráno)

Jakožto autor alternativní struktury dokumentace vám na ni napíšu kritiku, ale zatím na to nemám čas.

Určitě napiš a prosím co nejdříve! Aby nás to nějak extra nebrzdilo.

Shrnutí 2hého dne

• trochu jsme doladili https://dev.nette.org/…-dokumentace
  • na základě čehož vzniknul nástřel https://doc.nette.org/cs/new-hp
• byl doplněn https://wiki.nette.org/cs/syntax
• na základě shody jsme doplnili https://pla.nette.org/…taci-stranek
• dokumentaci jsme rozkouskovali na jednotlivé issue https://github.com/…teDoc/issues a následně celou prošli s stručně sepsali co je portřeba u čeho opravit/aktualizovat/doplnit/odstranit 
  • takže pokud někdo danému tématu rozumí a chce se podílet na tvorbě dokumentace má to „jednodušší“
• začali jsme pracovat na aktualizaci některých částí dokumentace
  • Běhové Prostředí
  • Formuláře
• zjistili jsme že jisté části dokumentace jsou hotové
  • Reflexe
  • Anotace
  • Latte Filter
  • Pokročilá makra
  • Dědičnost
  • Vlastní Makra
• zjistili jsme že budeme potřebovat těmto lidem zařídit oprávnění pro editaci dokumentace
  • pekelnik
• zjistili že se nám protáhne víkend i na dnešek (i dnes nás bude hodně pracovat na dokumentaci)

Celkové shrnutí (z mého pohledu)

Celkově se nám (snad) podařilo:

• Určit jakým stylem, způsobem a postupy dokumentaci psát.
• Doplnit informace potřebné k psaní dokumentace.
• Nastolit jednodušší přehled v tom co je a není potřeba kde udělat. (A jak to dělat)
• Ověřit že víc hlav doopravdy víc ví a kolaborace více lidí naráz je super.
• Ověřit že podobná akce dává smysl
• Posunout se zase o krok blíže k cíli (i když skoro nepatrný)
• Zjistit že Google Wave dává smysl a není úplně na nic (i když dnes došlo miniaturní ztrátě dat – desynchonizaci)

Těším se co nám k tomuto řekne sám Ó veliký až na tohle vlákno narazí.

A závěrem bych chtěl poděkovat hlavně Majkl578 za to že mě na myšlenku něco takového uspořádat navedl. dRaGen , HosipLan , pekelnik , Cifro , Jan Tvrdík bych chtěl poděkovat za velice aktivní přístup a všechm ostatním, kteří se zapojili, za to, že to s námi vydrželi.

EDIT:
Zdá se mě to nebo nefunguje (na webu) obarvování odkazů červeně pokud stránka neexistuje.

EDIT2:
Stále nemáme CSSko pro .[warning] (měkčí verzi .[caution] – jeho „žlutá“ varianta)

Editoval vrtak-cz (18. 6. 2010 6:07)

Nechápu, proč byste všichni chtěli předělat kapitolu šablony, která je jednou z nejlépe zpracovaných částí, místo toho, abyste řešili skutečné problémy v dokumentaci.

Ještě poznámka: Pokud je to alespoň trochu možné, nepřesouvejte stránky ručně. Ztrácí se tak jejich historie. Radši mi napište a já jim změním url bez ztráty historie.

Vytvořil jsem 1,5 stránky v dokumentaci formulářů.

• Formulářové prvky – Tady je ta půlka. Je to poněkud nezáživné téma, tak bych prosil nějakou dobrou duši o dopsání.
• Základní operace s formuláři – Tuhle stránku jsem vyrobil celou, abych nebyl nařčen z lenosti a opouštění práce v půlce.

Prosím tedy o revizi a připomínky.

K Základní operace s formuláři:

• Nechybí v druhém příkladu na továrničku to přidání do stromu komponent?
• Chybí tam klasická definice odeslání formuláře přes callbacky
• Mělo by tam být upozornění, že funkce „na místě“ jsou možné až od PHP 5.3

Dobrá, dal jsem tam jeden příklad na PHP 5.2.

Formuláře jsem měl původně mít na starosti celé já, takže díky za pomoc. :) Kdyžtak tě pak při dopisování kontaktuju.

Nevíte někdo jak je to s /--code pro Latte ???

Editoval vrtak-cz (18. 6. 2010 7:34)

„Ó veliký“ na vlákno narazil a je nadšen! Dnes v noci na PS nebo zítra až se dostanu po dvou týdnech opět ke komplu budeme řešit akutní úpravy webu, které budete potřebovat.

Před chvílí jsme se komunitně v pěti lidech shodli, že psaní dokumentace necháme našemu „Ó nejchytřejšímu“ Janu Tvrdíkovi. Nemá totiž smysl psát něco, co je špatně a on nám to přepíše (plýtvání naším časem, když Ó nejchytřejší to zvládne sám a nejlépe). :)

Majkl578 napsal(a):

Před chvílí jsme se komunitně v pěti lidech shodli, že psaní dokumentace necháme našemu „Ó nejchytřejšímu“ Janu Tvrdíkovi. Nemá totiž smysl psát něco, co je špatně a on nám to přepíše (plýtvání naším časem, když Ó nejchytřejší to zvládne sám a nejlépe). :)

A Honza má zásadní připomínky k něčemu jinýmu než ke stránce o komponentách, která je fakt špatná?

Tak ono by to nemuselo bejt nijak složitý.

.todo {background: #AEEC91; padding: 10px;}
body.normalni-clovek .todo {display: none}

tak by me tuze zajimalo, jestli se na PS nakonec neco dohodlo. chvilku sem tu debatu pozoroval, a prislo mi, ze se to toci neustale v kruhu (vymyslet strukturu, debatovat o ni, vymyslet ji jinak, debatovat o novem navrhu, …). jak na PS padlo – bez nekoho, kdo rekne „uz prestante (-me) vymyslet a dejte (-me) se do prace“ to nepujde.

a jsou nekde nejake pismenka k tomu, jak vypada aktualni navrh dokumentace, kam to smeruje, atd?… tu a tam bych taky neco doplnil, kdyz pri prgani na neco narazim. jenze by to chtelo take nejak vyjasnit si pojmy – aby pak nebyl tutorial, dokumentace, prirucka a FAQ skoro to same a precejen neco jineho.