Jak se dá opravit dokumentační bug

Školení, která pořádám

Valná část mé práce na PHP dokumentaci spočívá v opravování dokumentačních bugů. Jak se něco takového dělá? Pokud se nejedná o překlep nebo podobnou trivialitu, jsou bugy v zásadě dvou druhů:

  1. Původně byly reportovány jako problém v PHP a do dokumentačních bugů je přesunul nějaký vývojář jako vlastnost PHP hodnou zdokumentování. U takových bugů je potřeba zjistit, jestli už v dokumentaci náhodou funkčnost popsaná není. Pokud ne, je oprava většinou jednoduchá – stačí připsat jednu větu, odstavec nebo přidat příklad – předtím je ale nutné přečíst leckdy šťavnatou historii bugu.
  2. Pokud byl bug reportován přímo jako dokumentační, je potřeba nejprve ověřit, jestli se skutečně jedná o bug a jestli už náhodou nebyl reportován dříve. Dokud bylo v databázi třeba 150 otevřených bugů, dalo to docela práci, teď je situace naštěstí jednodušší. Výjimečně se také může stát, že chyba už je opravena v CVS verzi, ale nová verze ještě není na webu – tam se totiž někdy dostane třeba až po měsíci a čerstvější verze je k dispozici pouze přes Livedocs.

Reportovaný bug je následně vhodné pojmout jako celkový problém a ne jako pouhé zadání úkolu. Někdy je dokumentaci vhodné doplnit na jiné než navrhované místo, často je potřeba doplnit informaci o PHP verzi, ve které došlo ke změně, někdy je nutné chybu opravit na více místech manuálu, i když se popis týkal jen jednoho místa. Funkčnost popisovanou v bugu je také nutné nejen ověřit, ale je vhodné se podívat i do zdrojáků, jestli to náhodou není ještě trochu jinak, než to zvenku vypadá. Po zanesení změn do XML zdrojáků dokumentace je nezbytné zkontrolovat validitu dokumentu a případně se i podívat na HTML podobu.

Důkladná oprava většiny bugů tak zabere přinejmenším půl hodiny, i když z toho vzejde třeba jediná věta – to je smutný úděl opravovačů bugů.

Jakub Vrána, Ze zákulisí, 28.9.2005, diskuse: 7 (nové: 0)

Diskuse

Michal Molhanec:

Musím vám, autorům PHP dokumentace, pogratulovat, IMHO patří dokumentace PHP k těm opravdu dobrým. Jediné co bych současnému systému vytknul je, že IMHO moc nepočítá s třídama, to je asi největší slabina.

Jakub Podhorský:

jojo s tím musím upřímě taky souhlasit, ale to bude tím, že nikdo asi neočekával nějak valnou podporu objektů v PHP, která bych řekl že se tak či onak bude hodně rozšiřovat

Michal Molhanec:

Problém je i v tom, že potom třeba taková "Standard PHP Library" má dokumentaci mimo manuál, tím pádem i mimo stáhnutelné verze (třeba CHM), což je IMHO škoda.

Jakub Podhorský:

no SPL dokumentace je s prominutím "děsivá"(teda pro mě určitě) :( což mi přijde jako škoda...snad se to časem zlepší

Michal Molhanec:

mně nepřijde zase tak špatná (mám na mysli její doxygenovskou verzi)

Jakub Podhorský:

s tím souhlasím

ikona Jakub Vrána OpenID:

Je to jen dočasné: http://bugs.php.net/bug.php?id=30185

Vložit komentář

Používejte diakritiku. Vstup se chápe jako čistý text, ale URL budou převedeny na odkazy a PHP kód uzavřený do <?php ?> bude zvýrazněn. Pokud máte dotaz, který nesouvisí s článkem, zkuste raději diskusi o PHP, zde se odpovědi pravděpodobně nedočkáte.

Jméno: URL:

avatar © 2005-2018 Jakub Vrána. Publikované texty můžete přetiskovat pouze se svolením autora. Ukázky kódu smíte používat s uvedením autora a URL tohoto webu bez dalších omezení Creative Commons. Můžeme si tykat. Skripty předpokládají nastavení: magic_quotes_gpc=Off, magic_quotes_runtime=Off, error_reporting=E_ALL & ~E_NOTICE a očekávají předchozí zavolání mysql_set_charset. Skripty by měly být funkční v PHP >= 4.3 a PHP >= 5.0.