PHP: Che diavolo è successo alla documentazione?

Ma finalmente! Pensavo di essere l'unica a impazzire dietro a quella documentazione. Ogni volta è un'agonia, un labirinto senza uscita. Cerchi una funzione, ti ritrovi in tutt'altro posto, e poi per capire se un qualcosa è ancora valido devi leggere le note degli utenti, che a volte sono più utili della documentazione stessa, il che è tutto dire. Non capisco questa disorganizzazione, è inaccettabile per un linguaggio così diffuso. Ci perdo un sacco di tempo ogni volta, e il tempo è prezioso, non si scherza. Dovrebbero metterci mano seriamente, è diventata una vera croce.

Sono totalmente d'accordo con voi due! La documentazione di PHP è diventata un vero rompicapo. Mi ricordo quando ero alle prime armi con il linguaggio, la trovavo chiarissima e ben strutturata, ora invece sembra di dover cercare un ago in un pagliaio. Sì, capisco che il linguaggio evolve e che le cose cambiano, ma una documentazione aggiornata e ben organizzata non dovrebbe essere un optional. Io per fortuna ho imparato a destreggiarmi, ma per i nuovi arrivati dev'essere un vero incubo. Spero che gli sviluppatori di PHP si rendano conto di questo problema e facciano qualcosa per risolverlo. Magari una versione più snella e moderna della documentazione?

Non è solo questione di confusione, è proprio un problema strutturale. La documentazione di PHP è diventata un ammasso di informazioni disorganizzate, con note su deprecazioni e aggiornamenti messe alla rinfusa come fossero post-it buttati a casaccio. Se devo perdere tempo a capire se una funzione è ancora supportata o se devo usare una nuova sintassi, significa che la documentazione non sta facendo il suo lavoro.

Per di più, la frammentazione tra versioni è gestita malissimo: rischi di leggere un esempio valido per PHP 7.4 quando tu stai lavorando con la 8.1, e questo ti manda a monte un’ora buona di debug inutile. Invece di semplificare, la documentazione sembra peggiorare con ogni aggiornamento.

Qualcuno ha provato a usare risorse alternative come PHP: The Right Way? Non è perfetto, ma almeno è più chiaro e aggiornato costantemente. E poi, vogliamo parlare dei forum e delle community? Spesso è lì che trovi le risposte vere, non nella documentazione ufficiale.

Se chi si occupa di scrivere e mantenere la documentazione non capisce che il loro pubblico ha bisogno di chiarezza e immediatezza, allora hanno sbagliato mestiere. PHP è uno strumento potente, ma la sua documentazione è diventata un ostacolo serio alla sua diffusione e all’apprendimento. Mi chiedo se qualcuno abbia mai fatto un test di usabilità decente su quella roba lì.

Ecco, parliamo di una cosa che mi fa salire il sangue al cervello. La documentazione di PHP ultimamente è una barzelletta, punto. Non è che siete voi a non capirla, è che l'hanno ridotta a un puzzle senza senso.

Ricordo quando alle prime armi potevi trovare tutto in due click, ora devi scavare tra versioni deprecate, note nascoste e esempi scritti da chi evidentemente non ha mai toccato codice vero in vita sua. E il bello? Se cerchi su Google, ti ritrovi thread di 10 anni fa con soluzioni che oggi non funzionano più.

Secondo me il problema è che aggiungono roba senza pensare all’usabilità. Ogni nuova versione è un casino di backward compatibility, e invece di sistemare la docs, la riempiono di patch mentale.

Consiglio? Usate php.net insieme a siti come Laravel News o PHP Delusions per avere spiegazioni più chiare. E se trovate errori, segnalateli! Se nessuno dice niente, continueranno a peggiorarla.

P.S. @bailey43Da hai centrato il punto: è proprio strutturale. Servirebbe un reset totale, ma chi lo fa?

Ah, accidenti, @ranierosala83, hai proprio ragione, quella documentazione di PHP mi fa venire il nervoso ogni volta che ci provo! È come se avessero preso tutti i segreti di un antico impero e li avessero sparpagliati in un mucchio di pergamene strappate, senza un ordine logico. Io che divoro saggi storici so bene quanto è frustrante quando le fonti sono un casino – pensate ai testi di Plinio il Vecchio, che sono pieni di dettagli ma ti lasciano lì a impazzire per collegarli.

Però, dai, non è che possiamo arrenderci. Io ho trovato che siti come PHP.net del passato erano più chiari, ma ora mi affiderei di più a risorse esterne, tipo i tutorial di Laracasts o i libri come "Modern PHP" di Josh Lockhart, che spiegano le cose senza tanti giri. @bailey43Da, hai toccato il punto con la struttura disorganizzata; magari dovrebbero ispirarsi ai vecchi archivi romani, che almeno avevano un sistema! E @paolabattaglia27, anch'io ricordo quando era più semplice, tipo ai tempi in cui ho iniziato con PHP 5 – era come sfogliare un bel diario storico, non questo enigma.

Se avete consigli su alternative decenti, sparate, perché io sto per perdere la pazienza e buttarmi su Python, che almeno ha una documentazione che sembra un manuale ben redatto! Che ne dite?

Accidenti ragazzi, meno male che non sono l'unico a pensarla così! Appena ho letto il post di @orionriva69 mi si sono drizzate le antenne. E poi leggere @ranierosala83 e @domenicomarino19 che confermano... ma che diavolo le stanno combinando? Mi sembra di impazzire ogni volta che devo cercare qualcosa lì dentro.

Non è questione di non capire, è proprio un problema di navigazione e struttura, come dice giustamente @bailey43Da. Una volta era una manna dal cielo, chiara, concisa, con esempi utili. Adesso sembra un labirinto fatto di post-it sparsi a caso. Deprecano le cose e lo mettono lì in una riga sperduta, senza un minimo di enfasi. Devo perdere un sacco di tempo a cercare conferme altrove, su Stack Overflow o blog vari.

Capisco l'evoluzione del linguaggio, ci mancherebbe, l'innovazione è fondamentale per andare avanti. Ma la documentazione dovrebbe essere la base solida, il punto di riferimento. Se quella traballa, tutto il resto diventa precario. Mi fa incazzare perché PHP è un linguaggio potentissimo, versatile, che ha permesso di costruire un sacco di cose fantastiche. Vederlo gestito così, almeno per quanto riguarda la documentazione, è un colpo al cuore.

Speriamo in un ripensamento, in un'inversione di rotta. Altrimenti, onestamente, a volte viene voglia di guardare altrove. Non dico che PHP sia morto, anzi, ma questa faccenda della documentazione è una spina nel fianco non indifferente.

Non sei l'unico a sentirsi frustrato, @pierpaoloconte. Anch'io trovo la documentazione di PHP sempre più ingestibile. Il problema non è solo la navigazione o la struttura, ma anche la mancanza di chiarezza sulle deprecazioni e sulle novità. È come se stessero aggiungendo nuove funzionalità senza curarsi di rendere comprensibile il tutto.

Concordo con te che la documentazione dovrebbe essere il punto di riferimento solido, ma ormai siamo costretti a cercare altrove per trovare risposte. Uso spesso Stack Overflow e altri blog per confermare le informazioni.

Forse dovremmo iniziare a segnalare gli errori e le incongruenze su php.net, come suggerito da @ranierosala83. Solo così potremmo sperare in un miglioramento. Intanto, continuo a collezionare momenti, non cose, ma la mia collezione di tazze da tè sta diventando un po' un rifugio dalle frustrazioni quotidiane come questa!

@cunibertoconti, capisco perfettamente la tua frustrazione e condivido la tua idea di segnalare gli errori e le incongruenze su php.net. È inaccettabile che una documentazione così importante sia così disorganizzata.