Dokumentace: centrální bod ideologie

Webové stránky Nette prošly v posledních týdnech velkým vývojem. V tuto chvíli je třeba stanovit plán, jak obsah vytvářet. Rád bych na tomto místě vytvořil centrální bod ideologie, kde se sjednotí informace o tom, jakým směrem se má podoba webu ubírat.

Tento příspěvek budu postupně doplňovat a následující komentáře promazávat, aby stále zůstával aktuální. Následující slova nejsou dogma, o všem lze diskutovat. Občas si dovolím psát o dosud neimplementovaných věcech v přítomném čase.

Co vlastně chceme?

Diskuse o struktuře webu se musí odvíjet od úvah, co vlastně má čtenářům nabídnout:

• Základní informace o frameworku, akcích, novinkách – tedy titulní stránka s příslušenstvím
• Rychlé seznámení s frameworkem – úkol pro sekci Introduction, ve formě textu i videa
• Podrobný náhled do frameworku – úkol pro Programátorskou příručku
• Přehled tříd a metod – API reference
• Rychlé odpovědi na časté dotazy (FAQ)
• Návody, jak řešit specifické situace – stručné návody (How-Tos), podrobnější návody (Tutorials) & návody ve formě videí (Screencasts) (U)
• Jak řešit konkrétní problémy – Troubleshooting
• Sdílené repositáře – doplňky, komponenty, ukázky kódu, rozšíření (U)
• Co se chystá a děje v zákulisí? – blog lidí kolem frameworku, case studies, galerie webů (U)
• Jak se podílet na tvorbě obsahu?
• Jak se podílet na vývoji?

Ale také z pohledu, co má nabídnout pisatelům:

• Přidání vlastního obsahu – jmenovitě kódů, návodů, screencastů, řešení konkrétních problémů, blogpostů (U)
• Přidání feedbacku k obsahu – komentáře, bugreporty
• Možnost opravení a doplnění obsahu – web jako platforma otevřená všem, viz také oprávnění popsané níže
• Centrální řízení – tj. rozdělování a evidence úkolů a zodpovědností

Zároveň si třeba říci, že nic víc by na web patřit nemělo.

Uživatelský vs. oficiální obsah a oprávnění

Veškerý obsah na webu půjde rozdělit do dvou kategorií: uživatelský vs. oficiální. Technicky vzato se liší tak, že uživatelský obsah bude (i vizuálně) podepsaný autorem, oficiální obsah bude „anonymní“ (dílčí autory zjistíte pohledem do historie).

Uživatelský obsah může zakládat jakýkoliv registrovaný uživatel (podle přesných pravidel) a editovat jen jeho autor + úzká skupina moderátorů, kdežto oficiální obsah může zakládat a editovat mnohem širší skupina editorů (čítající samozřejmě i moderátory). O možnost stát se editorem může kdokoliv požádat, standardně se jím stává každý po napsání určitého počtu odpovědí na fóru. Autoři uživatelského obsahu mohou povolit volnější pravidla, třeba přístup pro editory, kteří jim mohou opravovat pravopisné chyby.

Z čtenářského hlediska se tak uživatelský obsah jeví jako série ucelených článků (i vícestránkových). Čtenář vnímá, že uváděné informace nejsou oficiálním stanoviskem. V přehledu výše je uživatelský obsah indikován (U).

Z oficiálního obsahu nevedou odkazy na uživatelský, naopak se odkazuje běžně.

Musím zdůraznit, že tento koncept neodpovídá konceptu Wiki. Mám za to, že nasazení Wiki u opensource projektů se neosvědčuje a vede ke vzniku netříděného nepořádku.

Podrobnější rozbor

Základní informace o frameworku, akcích, novinkách – základ je již k vidění na https://nette.org, takže nevyžaduje hlubší komentář. V plánu je přidat jednoduché rozhraní na vkládání nadcházejících akcí, zobrazovat nově přidaný obsah a rozšířit stávající informace, jako třeba učinit některé položky na stránce O frameworku rozklikávací.

Rychlé seznámení s frameworkem představuje sekce Introduction dokumentace (Getting Started, Downloading & Installation, Create Your First Application!). Jde o jediný tutorial, který bude spadat do oblasti oficiálního obsahu.

Podrobná programátorská příručka je také součást oficiálního obsahu. Informace v ní budou ze tří oblastí:

1. obecné info, introduction, FAQ, troubleshooting, slovníček, changelog + jak updatovat
2. kapitoly podle tematických oblastí, jako třeba: formuláře, routování, šablony, MVP. Kapitoly mohou mít i podkapitoly (odhalí se při rozkliknutí). Vše důležité je ale dostupné už z nejvyšší úrovně.
3. popisy tříd jako: Image, String

Především zde platí, že struktura se musí odvíjet od toho, co má smysl pro čtenáře. Tedy vytvářet „kapitolu“ o třídě String je nesmysl, stejně i naopak je nesmysl vytvářet „popis třídy“ PresenterRequest, kterou je vhodnější zmínit v kapitole o tvorbě MVC aplikací. Vzorový příklad tohoto dělení lze vidět na http://codeigniter.com/…ide/toc.html.

Každá stránka má titulek, perex a nanejvýš dvě úrovně nadpisů. Základní pravidla pro psaní stránek sepíšu, konkrétní se vyspecifikují za chodu. Vzorová podoba obsahu jednotlivých kapitol, co se týče jejich délky a četnosti ukázek kódu, je Zend, např. http://www.framework.zend.com/…duction.html. Vzorová podoba samotných příkladů kódu viz jQuery http://docs.jquery.com/Core.

Pár antipříkladů: příliš krátké a členité, příliš dlouhé.

API reference – přehled tříd a metod – hotová záležitost. Webová aplikace podporuje přímo odkazování do API (viz syntax), jakmile bude hotová příručka programátora, doplním i zpětné odkazy z API reference.

FAQ a slovníček pojmů bude součástí oficiální části odkazované v Příručce programátora. Obojí musí mít podobu stručných odpovědí v limitu cca dvou odstavců.

Jak řešit konkrétní problémy aneb Troubleshooting (alternativně Knowledge base). Součást oficiální dokumentace, strukturou připomíná FAQ, narozdíl o něj je libovolně obsáhlá a odpovědi jsou delší, nacházející se na samostatných stránkách. Příkladů je spousta, např. http://kb.eset.com/.

---

Jak řešit specifické situace – dostáváme se do vod uživatelského obsahu. Každý článek dostane nálepku:

• Tutorial: výukové příspěvky popisující krok za krokem řešení úlohy; tagem lze specifikovat obtížnost
• How-To / Cookbook: krátké příspěvky popisující jednu specifickou úlohu
• Screencast: vizuální forma návodů

Sdílené repositáře doplňků, komponent, ukázek kódů a rozšíření patří mezi stěžejní části webu. Jakožto uživatelský obsah se řadí po bok tutorialů a how-tos.

Přičemž veškerý uživatelský obsah mohou čtenáři doprovázet komentáři a hodnotit hvězdičkami. Příkladem nechť nám je třeba http://bakery.cakephp.org/. Je preferováno, aby autoři obohatily stránky piktogramem specifických rozměrů, zejména v případě komponent, tutoriálů a screencastů.

Co se chystá a děje v zákulisí? Tyto informace poskytuje především blog. Publikovat může každý, kdo o to požádá. Narozdíl od dokumentace jde o neformální, osobní žánr. Komentáře pod blogposty mohou, stejně jako jinde na webu, psát pouze registrovaní uživatelé. Mimo blogů je tu galerie webů používajících Nette, nebo případové studie.

Jak se podílet na tvorbě obsahu? Možnost přidávat nový uživatelský obsah musí být maximálně jednoduchá a přímočará, aby bylo hned jasné, co, kam a jak psát, proto vytvořím formuláře a mustry pro přidání pluginu, návodu atd. Vše popisuje nápověda, včetně syntaxe a pravidel strukturování textu. Pro autory screencastů bude připraven postup, jak video doplnit o standardizové intro, outro a stránky oddělující kapitoly.

Pro autory podílející se na tvorbě oficiálního obsahu bude existovat samostatná nápověda, kde by měly platit přísnější měřítka.

Verzování

Veškerý obsah lze štítkovat (tagovat) a jedním z tagů může být i číslo verze frameworku, pro který je psán. Příručka programátora a API bude navíc existovat na webu ve více kopiích pro příslušnou verzi (verze je součástí URL). Jelikož jsme nyní v poměrně výhodné situaci, kdy existuje dostatečně stabilní řada 0.9.x a na novinkové 1.0 se teprve začíná pracovat, není potřeba verzování vůbec řešit. Tj. v tuto chvíli stačí tvořit jedinou dokumentaci pro poslední stabilní verzi.

Jakmile vyjde první verze 1.0, celou Příručku programátora zduplikuji a přesunu na URL s číslem verze. Druhá kopie se bude moci přepisovat podle nové verze.

Adresářová struktura a subdomény

Současné rozdělení subdomén je následující:

• https://nette.org: Základní informace o frameworku, akcích, novinkách
• https://doc.nette.org: Programátorská příručka, Introduction, FAQ, slovníček, Troubleshooting (pracovní verze na https://doc.nette.org)
• https://api.nette.org: API reference
• https://pla.nette.org: uživatelský obsah, tj. How-Tos, Tutorials, Screencasts, ukázky kódu; ale také nápovědy pro tvůrce obsahu, popis syntaxe, blogy (dříve wiki.nette.org)
• https://dev.nette.org: wiki vývojářů a také autorů dokumentace
• https://addons.nette.org: uživatelský obsah v podobě pluginů a rozšíření
• https://examples.nette.org: příklady, zatím kloudně nevyužito

Centrální řízení

Momentálně probíhá na stránce https://dev.nette.org/cs/ndp a v diskusních vláknech spojených s jednotlivými stránkami. TODO seznam bych přepsal do formy aplikace, bode-li tato poptávka. Pokud jde o diskusní vlákna, zdá se mi, že bude vhodnější namísto propojení s fórem využít systém komentářů pod články. S tím, že komentáře editorů by byly oddělené (zřejmě využitím tabů), leč běžnému čtenáři neviditelné.