L'aggiornamento della documentazione prodotta e' uno degli aspetti piu' critici del lavoro collaborativo a causa della difficolta' nell'immissione dei dati e nel coordinamento tra i diversi autori, con il rischio di avere una documentazione incompleta, obsoleta o contraddittoria.
Wiki e' un strumento di GroupWare per creare e mantenere documenti web dinamici in modo semplice ed efficace usando un Web Browser. La stessa pagina Web utilizzata per la consultazione ne consente la modifica, che puo' essere realizzata da diverse persone.

La modifica avviene tipicamente con un meta-linguaggio (Markap Language), semplice da utilizzare, che verra' tradotto in HTML. Ad esempio la modifica della parte iniziale di questo tutorial avviene utilizzando una finestra di editing ed una sintassi del tipo:

Il lavoro di gruppo e' gestito grazie al blocco che un autore esercita su di un documento o di una sua parte al momento della modifica; il Wiki inoltre gestisce in modo semplice ed automatico le diverse revisioni dei documenti, consentendo rapidamente, con la funzionalita' "Differenze", di individuare le modifiche apportate ed eventualmente provvedere al ripristino di revisioni precedenti.

L'autenticazione degli utenti viene stabilita dall'amministratore che, a seconda dell'utilizzo, puo' attivare l'autoregistrazione, oppure utilizzare una infrasruttura di backend come puo' essere Ldap o PKI. In questo caso e' possibile creare policy di autorizzazione per singoli utenti o gruppi, applicate a singole pagine o a gruppi di documenti, i NameSpace, differenziando l'accesso in lettura e modifica

L'ambito di utilizzo prevalente e' quindi quello di una collaborazione ad un progetto comune, in cui il wiki rappresenta lo strumento condiviso per la documentazione.

Esistono piu' di 100 diverse implementazioni (http://www.wikimatrix.org/), con diverse caratteristiche specifiche. Mediawiki e' il Wiki più noto a causa del suo impiego nell'applicazione che ha reso popolare lo strumento Wiki: l'Enciclopedia Wikipedia.
Un'altro Wiki molto diffuso per la sua semplicita' e' Dokuwiki. Dokuwiki e' stato adottato dalla Commissione Calcolo e Reti dell'INFN come Wiki Centrale di riferimento per l'Ente: http://wiki.infn.it.

Nella seconda parte del tutorial vedremo quanto sia facile creare ed aggiornare documentazione utilizzando DokuWiki.

Un sito Dokuwiki contiene un insieme di documenti identificati da un nome ed eventualmente preceduto da un Namespace.

In questo esempio roberto.alfieri e' il Namespace e wiki-tutorial e' il nome. I NameSpace possono essere organizzati all'interno di una infrastruttura gerarchica per poter gestire in modo strutturato l'insieme dei documenti. Ad esempio roberto.alfieri:priv:documento_riservato ha due livelli di NameSpace. L'amministratore puo' attribuire policy di accesso specifiche per ogni NameSpace o singola pagina.

L'accesso al Wiki può avvenire in modo anonimo o autenticato. Gli utenti autenticati possono appartenere a uno o piu' gruppi. Per l'autenticazione l'amministatore puo' utilizzare un sistema interno di autoregistrazione o puo' utilizzare una eventuale infrastruttura di Autenticazione preesistente (e.g. LDAP). I permessi di accesso (lettura/modifica) ai NameSpace o ai singoli documenti vengono attibuiti dall'amministratore agli utenti, ai gruppi, a qualunque utente autenticato (@user) o agli utenti non autenticati (@ALL), mediante le ACL (Access Control List).

L'indirizzo URL di un documento Dokuwiki del tipo namespace:mydoc si compone nel seguente modo:

 http://server/dokuwiki/doku?id=namespace:mydoc

Un semplice modo per creare una nuova pagina consiste nel generare un URL di un documento che non esiste: dokuwiki presentera' una pagina per la sua creazione con il nome indicato nell'URL, ammesso che l'utente abbia i permessi necessari.

Se l'utente e' abilitato alla modifica, sul documento appaiono diversi pulsanti "Modifica" che consentono di entrare nell'editor dell'intero documento o solo di una sezione, acquisendone l'accesso esclusivo. L'editing avviene con un meta-linguaggio piu' semplice e piu' rapido da inserire rispetto all'HTML. Comunque ad un primo livello di utilizzo il documento puo' essere editato senza conoscere il meta-linguaggio, ma semplicemente utilizzando i "Pulsanti ad Accesso Rapido" disponibili sopra l'area di Editing.

Esistono inoltre Plugins che consentono l'editing WYSISYG (plugin:wysiwyg).

La sintassi Dokuwiki e' molto semplice e ben documentata: Syntax .
Il pulsante "Mostra Pagina" di un documento esistente ci consente di imparare rapidamente "per esempi".

La seguente tabella riassume, a titolo di esempio, i principali elementi per la formattazione del testo, confrontandoli con l'HTML:

Se l'amministatore dell'installazione lo consente, e' comunque possibile inserire direttamente parti del documento scritte in HTML. Ad esempio:

<html><font color="red">ROSSO</font></html> diventa: ROSSO

In alcuni casi e' utile visualizzare testo senza formattazione (righe di codice, caratteri speciali, parole chiave, ..).
L'interprete Dokuwiki puo' essere disbilitato delimitando il testo senza formattazione con il tag <nowiki>, come ad esempio <nowiki>//italic//</nowiki>

Il testo non formattato puo' essere incluso in specifici riquadri:

Due spazi all'inizio della riga disabilitano l'interprete per i caratteri dell'intera riga.

Si puo' creare un'area di testo non formattato delimitandola con i tag <code> </code>. Grazie al supporto di GeSHi (Generic Syntax Highlighter) il tag <code> può evidenziare codice sorgente in modo da renderlo più facile da leggere. Il seguente esempio e' delimitato da <code java> </code> :

class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Visualizza la stringa.
    }
}

Se esistono piu' di 3 intestazioni (di livello 1, 2 o 3) l'indice del documento viene generato automaticamente in un opportuno riquadro della pagina.
L'indice automatico puo' essere disabilitato includendo la stringa ~~NOTOC~~ nel documento.
Le intestazioni dal livello 1 al livello 5 si creano così:

Dokuwiki supporta liste ordinate e non-ordinate. Per creare un elemento di una lista bisogna indentare il testo con due spazi e usare un asterisco (*) per le liste non ordinate oppure un trattino (-) per quelle ordinate.
Per creare sottolivelli di liste basta aggiungere altre coppie di spazi iniziali.

   * Primo elemento 
   * Secondo elemento 
     * Terzo elemento

• Primo elemento
• Secondo elemento
  • Terzo elemento

I link possono essere riferiti a collegamenti esterni o ad altre pagine interne di Dokuwiki. E' previsto il supporto per le principali applicazioni di documentazione Web (Wikipedia, Google, ..). Gli indirizzi e-mail possono essere oscurati per proteggerli dallo Spam. Esempi:

Le immagini possono essere interne o esterne. Le immagini interne sono caricate con lo strumento di Upload.
Per attivare la finestra di Upload bisogna entrare nell'editor e selezionare il pulsante per inserire immagini.

L'upload e' possibile per un insieme di tipi di file wiki:mime.
Le immagini possono essere incluse nel documento inserendo il nome tra doppie graffe con diverse opzioni possibili, quali:

Se si specifica il nome di un file (esterno o interno) che non è un'immagine (gif, jpeg, png), allora esso sarà visualizzato come collegamento.

Una tabella si puo' creare semplicemente delimitando gli elementi delle righe con il carattere | (pipe). Piu' Pipe adiacenti fondono gli elementi delle riga (ColSpan). Esempio:

| Riga1 Colonna1 | Riga1 Colonna2 | Riga1 Colonna 3 |
| Riga2 Colonna1 | Riga2 Colonna2 | Riga2 Colonna 3 |
| Riga3 Colonna1 | Riga3 Colonna2 e Colonna 3 ||

Il carattere ^ al posto di | attibuisce il significato di intestazione all'elemento che segue. Inoltre per allineare il testo di una cella basta aggiungere 2 spazi a destra e/o a sinistra:

^  Colonna1^ Colonna2  ^Colonna3  |
| Riga1 Colonna1 | Riga1 Colonna2 | Riga1 Colonna 3 |
| Riga2 Colonna1 | Riga2 Colonna2 | Riga2 Colonna 3 |
| Riga3 Colonna1 | Riga3 Colonna2 | Riga3 Colonna 3 |

Al Dipartimento di Fisica e' attivo un server Dokuwiki Dipartimentale

Si autentica al Dominio Fisica. Sono quindi riconosciuti (con le stesse credenziali username/password della posta) tutti gli utenti del Dipartimento. Ogni utente puo' avere un proprio NameSpace Personale del tipo [[nome.cognome:documento]] leggibile da tutti e un Namespace [[nome.cognome:priv:documento]] visibile solo al proprietario.
Si possono creare anche NameSpace per Gruppi, con le stesse policy dei Namespace personali.

Roberto Alfieri — 2008/07/08