Modulo di documentazione e assistenza

Alcuni moduli non richiedono realmente che tu faccia nulla e semplicemente eseguono le loro funzioni dietro le quinte. Tuttavia, questi moduli probabilmente non hanno impostazioni configurabili o servono solo come dipendenze per altri moduli.

Più spesso, il modulo che ti interessa è uno per il quale puoi configurare autorizzazioni e impostazioni. Alcuni progetti sono facili da usare, cioè il loro utilizzo è “intuitivo”, e ti sarà relativamente chiaro cosa puoi configurare e cosa devi fare per ottenere ciò che desideri.

Se desideri conoscere tutti i dettagli necessari per utilizzare in modo intelligente il modulo che hai appena installato, posso suggerirti alcune cose che potrebbero esserti utili o luoghi in cui guardare.

Le seguenti proposte sono ordinate in base alla facilità d’uso.

Purtroppo, per gli utenti finali principianti come noi, Drupal è in costante evoluzione, e anche se siamo fortunati a poter beneficiare liberamente del lavoro immenso degli sviluppatori, il loro tempo è limitato, e credo si possa dire con certezza che i migliori sviluppatori non tendono a essere i più diligenti autori di documentazione per i principianti come noi — altrimenti né tu né io saremmo qui ora.

Ti consiglio di documentare e pubblicare le tue prove ed esperienze mentre impari a usare Drupal, per il bene delle migliaia di persone che si troveranno nella tua stessa situazione nei prossimi giorni, mesi e anni.

Considero questa una questione fondamentale per la creazione di questa documentazione, nonostante (o a causa di) le infinite frustrazioni e difficoltà — nell’uso della nuova sezione di documentazione di Drupal — e, in misura minore, nell’apprendimento e uso di Drupal, problemi che avrebbero potuto essere evitati se altri principianti come te e me avessero già creato istruzioni adeguate per i neofiti. Ma sono particolarmente felice che tu, mio amico, possa trarne beneficio.

Tu, come me, non hai bisogno di sapere nulla di “sviluppo” o programmazione per condividere ciò che “sai” e hai imparato.

Metodo per tentativi ed errori

Puoi semplicemente iniziare a utilizzare il modulo o sperimentare con le sue impostazioni.

Nei casi in cui, dopo aver esplorato da solo, non riesci a capire cosa fa un’opzione o quali potrebbero essere tutte le possibili conseguenze del suo utilizzo, puoi semplicemente provare ciò che la tua indole avventurosa ritiene migliore.

Ogni volta che raggiungi un punto in cui il modulo richiede supposizioni da parte tua, non devi preoccuparti di provare qualsiasi opzione disponibile, poiché il backup del tuo sito ti permetterà sempre di tornare alla versione precedente del tuo sito. Fai sempre il backup del tuo sito, vero?

Poiché non è sempre ovvio quali effetti un modulo o una specifica opzione possano avere sul tuo sito, ti consiglio di provare un solo modulo alla volta, esplorando ogni parte del tuo sito e provando a usarlo in tutti i modi possibili — creando nuove pagine e testando diverse configurazioni — prima di aggiungere un altro modulo contrib.

Altrimenti, se abiliti più moduli contemporaneamente e poi riscontri problemi o comportamenti strani, non saprai quale dei nuovi moduli è responsabile dei problemi.

Contenuto della pagina del progetto

Ogni pagina di progetto di un modulo è la sua home page su drupal.org. È la prima pagina che visito quando penso di provare un modulo o quando incontro problemi o ho domande su un modulo appena attivato.

Se leggi attentamente l’intera pagina del progetto, puoi essere relativamente sicuro di avere tutte le informazioni più importanti di cui hai bisogno. Ad esempio, se stai valutando se provare un modulo, eventuali dipendenze necessarie per il suo funzionamento saranno elencate nella pagina del progetto.

La pagina del progetto può anche contenere altri link utili relativi a molti aspetti di quel modulo.

Il contenuto della pagina del progetto può essere destinato a nuovi utenti Drupal oppure orientato a utenti più avanzati o sviluppatori.

Link “Leggi la documentazione” nella pagina del progetto (se presente)

Nella colonna di destra (che si sposta in fondo alla pagina sui dispositivi mobili o in finestre del browser strette) troverai sempre il titolo “Risorse”, sotto il quale potresti trovare un link “Leggi la documentazione”.

Tuttavia, non tutte le pagine di progetto hanno un link “Leggi la documentazione”, e in tal caso, si spera che troverai link utili alla documentazione nell’area principale dei contenuti della pagina del progetto.

Quando il link “Leggi la documentazione” è presente, rappresenta la risorsa che gli sviluppatori considerano più appropriata per iniziare la ricerca di ulteriori informazioni.

Il contenuto di ogni pagina del progetto è determinato e controllato dal creatore originale del progetto e, eventualmente, da alcune altre persone a cui il creatore ha concesso i permessi di modifica.

Altri contributori di drupal.org, che non hanno accesso per modificare la pagina del progetto, spesso creano altre pagine con ottime informazioni sul modulo di tuo interesse. Purtroppo, però, queste altre pagine raramente sono collegate dalla pagina del progetto.

La ricerca di tali pagine non collegate sarà trattata di seguito nella sezione sulla ricerca Google limitata a drupal.org ⤵

File “README.txt” del modulo

Storicamente, il file “README.txt” era il luogo ufficiale in cui venivano documentate tutte le informazioni realmente importanti e necessarie per un modulo (o tema), comprese quelle relative all’aggiornamento del modulo (o tema) a una versione più recente.

Il file README.txt si trova nella cartella principale del modulo contrib (o tema) dopo l’estrazione, se esiste.

Per visualizzare il file README.txt del modulo (o tema) senza scaricare nulla, visita:

http://cgit.drupalcode.org/project/PROJECT_MACHINE_NAME.git/blob/HEAD:/README.txt

Sostituisci PROJECT_MACHINE_NAME nell’URL sopra con il nome macchina specifico del progetto.

Il “nome macchina” si trova nell’URL nella barra degli indirizzi del browser quando sei su qualsiasi pagina del progetto drupal.org, come la parte “PROJECT_MACHINE_NAME” in questo esempio:

https://www.drupal.org/project/PROJECT_MACHINE_NAME

Se il file README.txt non esiste, probabilmente si tratta di un modulo senza impostazioni configurabili che funziona semplicemente in background ed è necessario per altri moduli contrib.

Se il file README.txt non è presente o vuoi esplorare tutta la documentazione del progetto, usa il seguente URL (sostituisci “PROJECT_MACHINE_NAME”):

http://cgit.drupalcode.org/PROJECT_MACHINE_NAME/tree/?id=HEAD

Nell’angolo in alto a destra di questa pagina su “drupalcode.org”, potresti dover “passare” alla versione del core Drupal che desideri esaminare.

Ricerca Google limitata a drupal.org

Se vuoi limitare la ricerca all’intero sito drupal.org, ecco cosa faccio io. Uso spesso questo metodo per cercare su drupal.org o su qualsiasi altro dominio di mia scelta.

Vado su google.com ⎘ e digito:

site:drupal.org

Nota che dopo i due punti (“:”) non c’è spazio prima del nome del dominio. E non usare “www.” all’inizio di nessun dominio.

Aggiungi uno spazio dopo il dominio e inserisci le parole chiave pertinenti — in questo caso, il nome del modulo.

A volte trovo utile limitare la ricerca specificamente a “Drupal 8” (invece di ottenere risultati anche per D6, D7, ecc.) aggiungendo “Drupal 8” nel campo di ricerca di Google. Utilizzando le virgolette doppie, Google restituirà i risultati che contengono esattamente quella frase.

Per vedere quali informazioni sono disponibili per un modulo in tutto il web, comprese le pagine dentro e fuori drupal.org, rimuovi “site:drupal.org”.

Per ottenere 100 risultati di Google per pagina invece di 10, quando ti trovi su una pagina dei risultati di Google, fai clic sull’icona dell’ingranaggio in alto a destra e seleziona “Impostazioni di ricerca”. Nella pagina successiva, sotto “Previsioni istantanee di Google”, seleziona “Non mostrare mai risultati istantanei”. Poi sotto “Risultati per pagina”, trascina il cursore completamente a destra. Le tue ricerche impiegheranno solo qualche frazione di secondo in più.

Opinione personale: potresti pensare di usare il motore di ricerca fornito da drupal.org in cima a tutte le sue pagine. L’ho provato diverse volte e ti consiglio di provarlo anche tu… se ti piacciono gli esercizi inutili.

Pulsanti / link “Guida” nella pagina “Estendi” del tuo sito (se presenti)

Nella pagina “Estendi” del tuo sito, a destra del nome di ogni modulo, puoi vedere la prima riga della sua descrizione, se la finestra del browser è abbastanza larga.

Se fai clic su questa prima riga, la descrizione si espande verso il basso rivelando il resto del testo, nonché i pulsanti/link “Guida”, “Autorizzazioni” e “Configura” per quel modulo, quando disponibili.

Se non vedi subito la prima riga della descrizione del modulo a destra del suo nome e vuoi visualizzarla, segui le istruzioni sulla pagina di configurazione del modulo.

Purtroppo, per accedere alla pagina di aiuto di un modulo sul tuo sito, devi prima importare e abilitare il modulo stesso. Inoltre, il pulsante/link “Guida” sarà visibile solo se il modulo è abilitato. E, sfortunatamente, non tutti i moduli contrib o core hanno un pulsante/link “Guida”, quindi non potrai sapere se è disponibile finché non attivi il modulo.

Per queste ragioni, non mi sono mai affidato ai pulsanti “Guida”, anche se, osservandoli ora, vedo che spesso conducono a pagine contenenti informazioni utili.