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ů:

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.
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.

28.9.2005 18:30:30

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

28.9.2005 22:02:53

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.

29.9.2005 17:28:33