ApiGen: tipy na vylepšení homepage

Vypadalo to, že ApiGen umřel, takže jsem rád, že @TomášVotruba pokračuje dále ve vývoji. Měl bych pár poznámek k vylepšení zejména homepage. Píšu to sem, protože ApiGen vnímám jako projekt úzce související s Nette a nechci (zatím) otevírat několik issue, protože jde spíš o úvahy.

Instalace

Je super, že ApiGen opustil PEAR, díky tomu jej můžu dropnout i u Texy. Nicméně instalace pomocí

$ curl -sS http://apigen.org/installer | php

je stále příliš složitá, neboť nefunguje na Windows, kde curl standardně není. Není jednodušší nabídnout přímo apigen.pear ke stažení? Tak jak je v releases?

Instalace „Using Composer as dependency of your project“ a stejně tak „Using Composer globally“ jsou fundamentálně špatně. Existuje jen jeden jediný způsob, jak instalovat ApiGen pomocí Composeru, a tím je příkaz composer create-project, neboť ApiGen je projekt, nikoliv knihovna.

Homepage

Když už jsme u instalace, na homepage chybí viditelné tlačítko „Download ApiGen“ v horní části stránky, které stáhne aktuální phar. Odkazovat kvůli instalaci na GitHub je IMHO jen překážkou navíc, nehledě na to, že odkaz je umístěn až pod ohybem.

Odkaz „Take a look at an example.“ je nevyužitá příležitost. ApiGen má dnes reference, kterými se může (MUSÍ!) pochlubit:

• Amazon Web Services
• Doctrine
• CakePHP (teď už bohužel přebrandovaný na CakePHP API Docs…)
• a určitě další

Tohle je potřeba prodat.

Zároveň @juzna.cz kdysi vytvořil online generátor dokumentace na http://apigen.juzna.cz – nevím, jestli to ještě funguje, ale pokud ano, je třeba to propagovat na čelním místě stránky: „Vyzkoušejte si ApiGen na svém projektu!“

Features

Fakt nikoho nezajímá, že „Our own TokenReflection library is used“, už vůbec ne jako bod č. 1. Informace o použitých knihovnách, ať už jde o TokenReflection, Nette nebo Latte, bych ponechal v patičce. Uživatelům je to šumák.

Co je skutečná přednost ApiGenu? Čím se liší od jiných systémů? Když jsem psal první verzi, tak z mého pohledu ta killer feature byla

1. Přehlednost (tohle byl standard phpDocumentor, tohle byl ApiGen).
2. Podpora nových vlastností PHP
3. Rychlost (2 minuty phpDocumentor versus 11 sekund ApiGen)

Netuším, jak je dnes na tom phpDoc nebo jiné systémy, rychlost možná už nehraje žádnou roli, ale přehlednost je stále výhoda, kterou se dá odlišit od konkurence a na kterou člověk uslyší. Kdo nechce mít přehlednou dokumentaci?

Přitom není ve výčtu vlastností vůbec uvedena.

Klidně bych nahradil titulek „API documentation generator for PHP“ za „Chcete přehlednou dokumentaci?“