Linee Guida Documentazione Italiana

Linee Guida per collaborare nel migliore dei modi alla Documentazione italiana di Drupal
Premetto che tutto quello che trovate qui non sono nè imposizioni, ne profezie ma solo punti chiave che durante precedenti discussioni hanno ricevuto sufficente approvazione da essere essere inserite come punti condivisi, siete comunque liberi di commentare e discutere i punti sotto indicati.

Documentazione completa
Tabella Modifiche della Documentazione

Struttra Documentazione Italiana

Con che tipo di contenuti si può contribuire? L'idea è quella di creare una documentazione che via via stringe il cerchio sull'argomento.
• Guide: è la guida nelle più classiche modalità che tutti conosciamo, in riferimento a Drupal devono essere guide di tipo "generico", che spieghino in dettaglio o meno, il funzionamento ed il comportamento e l'uso generale di qualsiasi componente di Drupal; ovviamente è meglio partire dalle componenti del Core di Drupal per poi passare ai contributi, ma essenzialmente non deve essere spiegato come si realizz qualcosa, ma piuttoso cos'è, cosa può fare e come si usa nelle sue modlalità base; per chiarire meglio gli argomenti può indcare uno o più documenti dei punti successivi;
• How To / Tutorial: quese sono guide che spiegano come realizzare qualcosa nello specifico, come integrare diversi componenti di Drupal per avere un certo risultato, in altri termini si spiega come risolvere, creare o realizzare un certo risultato; per chiarire meglio gli argomenti può indcare uno o più documenti del punto precedente o successivo;
• Faq: è il timpo di supporto più semplice che esiste, deve rispondere essenzialmente ad un aspetto: l'essere sintetico; La domanda deve proporre una problematica specifica o più problematiche correlate, ma rimanendo sempre fissi un problema solo; la risposta e quindi la soluzione alla problematica o dubbio messo in evidenza dalla domanda, deve essere altrettanto sintetica e concisa all'argomento, deve dare direttamente la soluzione o la risposta alla domanda senza varie argomentazione; per chiarire meglio gli argomenti può indcare uno o più documenti dei punti precedenti;

Come devono essere scritti contenuti? Sono solo consigli su come realizzare le guide, in questo modo si semplifica il lavoro di chi deve revisionare le guide ed aumenta le possibilità che la tua guida possa essere inclusa senza ulteriori modifiche che l'autore non aveva previsto.
• Semplicità e Chiarezza;
• Prestare attenzione alla Versione di Drupal che si sta trattando, eventualmente aggiungere semplici note del tipo "non testato su d5, d7 ...";
• Pochissimo codice, in caso si necessità l'uso di codice meglio un link, ad ogni modo il consiglio è non esagerare e cercare di rendere la guida fluida durante la sua lettura e non interrompere troppo il discorso con codici interminabili;
• Per il punto precedente penso sia inevitabile una "eccezione" per la categoria "How To" e "Tutorial", ma sempre nel limite del possibile;
• Quando si scrive del codice PHP usare <?php ?> anzichè i tag code;
• Quando si inserisce del codice PHP cerchiamo di usare i "coding standard", se chi usufruisce dei codici si abitua a leggere in un certo modo quando scriverà sarà "avvantaggiata";
• Evitiamo i duplicati, meglio integrare ed ampliare;
• Quando si edita un documento esistente ricordarsi di inserire un "Log" che indichi in modo esaustivo le modifiche fatte così da facilitare l'opera di revisioni da parte degli altri utenti;

Possono essere inseriti contenuti esterni? I contenuti provenienti dall'esterno è un problema piùttosto delicato quindi è meglio fare chiarezza sull'argomento prima di incappare in problemi o moderazioni inaspettate.
• Se si è gli autori, il problema non si pone, ad ogni modo cerchiamo di rendere anche le guide "libere" come lo è il software se no gli sforzi saranno vani;
• Se non si è l'autore del contenuto?
• Controllare la Licenza;
• Se non ci sono indicazioni sulla licenza contattare l'autore;
• Ad ogni modo il link può essere usato tranquillamente;