Jak se vytváří PHP dokumentace
Školení, která pořádám 
Mám tu čest, že patřím k aktivní autorům anglické PHP dokumentace. Způsob, jak se na ní pracuje, je podrobně popsán v PHP Documentation HOWTO, základ je ale poměrně jednoduchý.
- Je potřeba PHP perfektně rozumět (nebo alespoň nějaké jeho části). Poznámky lidí, kteří tento předpoklad nesplňují, se většinou objevují mezi User Contributed Notes a není divu, že jich je většina bez náhrady smazána. Abych poznámkám nekřivdil, tak čas od času se v nich objeví hodnotná informace a důležitá část tvorby dokumentace spočívá právě ve zpracování těchto poznámek. Z tohoto důvodu jsem opravdu rád, že PHP dokumentace není vytvářená pomocí Wiki nebo podobného systému.
- Je potřeba ovládat CVS a pro přímou editaci také mít vlastní CVS účet. Ze začátku je ale stejně lepší vytvořit pár patchů a poslat je do konference. Jednak si ověříte, že jste práce na dokumentace schopni a jednak se tím nenápadně ověří vaše schopnosti.
- Výhodou je znát Docbook nebo syntaxi alespoň okoukat ze stávajících zdrojáků PHP dokumentace.
A to je vlastně vše. Já dokumentaci hlavně opravuji v případě, když při jejím čtení narazím na nějakou chybu, fixuji dokumentační bugy, zařídil jsem, že se v příkladech a uživatelských poznámkách zvýrazňuje PHP kód, vytvořil a aplikoval jsem skript pro ověření správného počtu a typu parametrů funkcí podle zdrojáku PHP nebo jsem zařídil provázání seznamu konfiguračních direktiv s jejich vysvětlením.
Určitou dobu jsem pracoval i na českém překladu dokumentace, to jsem ale po nějaké době vzdal, protože jednak to sám nevyužiji (pokud občas neznám některé anglické slovo, stačí ho vložit do schránky a slovník, který používám, ho pohotově přeloží) a jednak to je práce značného rozsahu. Kromě toho, že je spousta stránek zcela nepřeložených, je jich také spousta zastaralých (to je ještě horší) a navíc se anglická dokumentace pořád rozšiřuje. Nicméně pokud máte chuť, je to určitě velice prospěšná práce.
Diskuse
Michal Ludvig:
Pche, to je slovo do pranice. Vzdycky kdyz nekde prohlasim, ze prekladat dokumentaci je zbytecny a kontraprodukivni, protoze preklady jsou vecne zastarale a neaktualni a tudiz nadelaji vic skody nez uzitku, tak se na me sesype hromada lidi, kteri naopak tvrdi jak je to uzitecna a bohuliba cinnost. IMHO by lidi meli umet anglicky kdyz hodlaji programovat, administrovat servery nebo delat podobne "pokrocile" cinnosti :-)
spaze:
tak nejak me napadlo.. k tomu prekladu.. videl jsem jeden peknej: Volume jako "hlasitost" ve spravci diskovejch oblasti (ci tam nekde) ve woknech XP :)
(jinak dobra prace a souhlas s cz manem, mozna by bylo lepsi ho uplne dropnout)
spaze: 
llook:
Já používám cs verzi v odkazech v diskuzi. Ale sám používám anglickou, protože stránky, které jsou anglicky a nadpisy mají česky jsou mnohem hůře čitelné než ty celoanglické.
Myslím, že zejména pro začátečníky (kteří předtím nebyli programováním motivováni k učení angličtiny) je částečný překlad neocenitelný. Kdyby neexistoval, určitě by polovina dotazů v diskuzi byla "co dělá funkce XY?".
llook: JohnyB:
Jo, Sprava > Sprava disku > Vlastnosti jednotky > HW > Vlastnosti ;)) Kdysi jsem ti to tusim posilal :D<em>anonymní</em>:
No konečně vím, kde si ztlumit hlučný disk :-)JersyWoo:
Angličtina, to znám o tom jsem viděl pořad v televizi, aber ich spreche Deutsch und du?Adam:
Neboj, manual PHP sprechti i nemecky a predpokladam, ze nemecky preklad bude o neco aktualnejsi a obsahlejsi nez cesky http://www.php.net/manual/de/ (ale s mou neznalosti nemciny to nepoznam ;)
Jakub Vrána 
:
Stav jednotlivých překladů lze zjistit např. na http://phpdocmanager.sourceforge.net/revcheck/. Použitelný je v podstatě pouze francouzský překlad.
Jakub Vrána : Tomáš (ATom):
S Docbookem jsem něco málo dělal. Ale docela mě zajímá, jak se řeší právě ta multi jazykovost.Myslel jsem, že pokud něco přeložíš do češtiny a autoři anglické verze udělají v to dokumentu změnu, tak se automaticky použije při kompilaci anglická verze, do té doby než český překladatel daný překlad aktualizuje. Tomu tak není?
Pro začátečníky je český překlad opravdu velké plus. Většinou jim stejně nejde o nic moc složitého. A navíc i pro někoho, kdo anglicky moc neumí je mnohem jednodušší pochopit popis nějaké funkce, než text vysvětlující principy a syntaxi PHP.
Jakub Vrána :
Anglická verze se použije jenom v případě, kdy odpovídající část vůbec není přeložena. Dává to smysl, protože málokterý jazyk změny stíhá.
Livedocs (budoucí systém prezentace dokumentace, mám o něm napsaný článek) to řeší lépe - na základě stáří a počtu změn v přeloženém dokumentu může zobrazit anglickou verzi i v případě, že přeložená existuje.
Jakub Vrána : Diskuse je zrušena z důvodu spamu.
© 2005-2024 