Documentazione
Da Gestione Contenuti - EPS.
L'accesso alla Guida di Enterprise Portal System (EPS), in CMS sviluppato da Infotel Telematica, è libero. Gli utenti registrati che utilizzano il sistema di gestione dei contenuti possono inoltre contribuire al wiki integrando le pagine di documentazione con i loro consigli e suggerimenti, condividendo con gli altri esperienze e soluzioni.
Questo wiki presenta delle regole e delle indicazioni di stile da seguire accuratamente quando si crea una nuova pagina o quando se ne modifica una già esistente. Tali regole ci permettono di mantenere ordinati i contenuti del wiki e di renderli disponibili agli utenti in modo agevole.
Creare una nuova pagina
Segui scrupolosamente questi passi per scrivere una nuova pagina di documentazione.
Registrazione
Per modificare qualsiasi pagina occorre innanzitutto essere registrato al wiki, per registrarsi:
- Cliccare in alto a destra nella pagina su "Entra/Registrati";
- Alla dicitura "Non hai ancora un accesso?" cliccare "Crealo ora";
- Inserire un nome utente, una password ed un indirizzo e-mail valido e cliccare "Crea un nuovo accesso";
- A questo punto si dovrebbe aver ricevuto una e-mail richiedente una conferma (controllare anche la posta indesiderata, nel caso non comparisse fra le e-mail ricevute);
- Una volta cliccato il link di conferma la procedura è finita e si può accedere al wiki come utente registrato semplicemente cliccando su "Entra/Registrati" e inserendo i propri username/password.
Cosa vuoi scrivere?
Scegli il modello di composizione appropriato e copia il sorgente (clicca su Modifica per visualizzare il sorgente).
- Modello di procedura (per descrivere una procedura standard, usato ogni volta che si dovrà spiegare all'utente come agire per raggiungere un determinato obbiettivo)
- Modello di descrizione (per spiegare un concetto, usato ogni volta che si dovranno spiegare all'utente concetti teorici,per esempio la struttura della piattaforma)
- Modello di consultazione (per liste o tabelle da consultare, usato per la consultazione dei valori possibili di determinati campi)
- Modello di consultazione per novità di una versione software (per pagine contenenti migliorie e novità della piattaforma)
- Modello di codice (per descrivere del codice, standard (es. funzioni di libreria) o sviluppato per esigenze particolari)
- Modello per il glossario
Crea la nuova pagina
- Effettua una ricerca con il nome della pagina che vuoi creare
- Suggerimento per il titolo (senza articoli):
- Procedura -> es. "Aggiungere una tabella dati" (usare il verbo dell'azione)
- Descrizione -> es. "Applicazioni" (usare il sostantivo)
- Consultazione -> es. "Vettori di sistema" (usare il sostantivo)
- Suggerimento per il titolo (senza articoli):
- Se la pagina non esiste, clicca su "E' possibile crearla ora"
- Incolla nella pagina il sorgente del modello
- Per prima cosa, compila la sezione Categorie del tuo testo (in fondo; per le opzioni disponibili, vedi le liste nella sezione seguente, "Opzioni per la sezione Categorie")! Per capire perché questo è importante, e perché dovresti già sapere cosa scrivere lì subito dopo aver creato la pagina, leggi le domande e risposte.
- Scrivi la documentazione seguendo lo schema del modello che hai scelto.
Dubbi di scrittura? Leggi la nostra Guida di stile!
La Guida di stile contiene diversi suggerimenti ed esempi per risolvere i dubbi che possono venire quando scrivi. Leggila, e segui le convenzioni indicate.
Opzioni per la sezione Categorie
| Tema | Sigla da usare |
|---|---|
| Configurazioni | configurazioni |
| Versioni | infoversioni |
| Moduli | moduli |
| Struttura | struttura |
| Assistenza | assistenza |
| Gestione della struttura | procedurestruttura |
| Procedure di amministrazione | procedureamministrazione |
| Gestione dei contenuti | procedurecontenuti |
| Problemi frequenti e soluzioni | soluzioni |
| Liste di parametri | parametri |
| Applicazioni | applicazioni |
| Funzioni di libreria | funzioni_libreria |
| Struttura del sistema | struttura_sistema |
| Destinatario | Sigla da usare |
|---|---|
| Utente Full | utentefull |
| Utente Light | utentelight |
| Utente Backoffice | utentebackoffice |
| Utente sviluppatore | sviluppatore |
| Utente amministratore | amministratore |
| Utente redattore | redattore |
| Utente pubblicatore | pubblicatore |
Domande e risposte
Perché tutte queste complicazioni?
Questo wiki ha quattro scopi:
- Rendere facile la scrittura della documentazione.
- Permettere a più persone di collaborare alla creazione della documentazione.
- Ottenere documentazione facile da aggiornare.
- Ottenere documentazione dalla quale sia facile estrarre automaticamente solo le parti che servono per scopi o destinatari specifici.
Per centrare questi obiettivi, è stato creato un metodo di scrittura che richiede a chi scrive un piccolo sforzo di adattamento.
Perché devo per forza usare uno dei modelli di composizione? Non posso cominciare a scrivere e basta?
I modelli di composizione sono stati impostati per ottenere una documentazione centrata sulle esigenze di chi la dovrà usare, NON di chi la scrive. Questo è molto importante per creare documentazione che venga poi effettivamente e utilmente utilizzata quando serve e dalle persone alle quali serve.
Ho tante cose da scrivere. Da dove comincio per decidere l'argomento e il titolo?
L'errore più grave che puoi commettere quando scrivi in questo wiki è scrivere cose diverse nella stessa pagina di documentazione. E' necessario sforzarsi di scrivere su un solo argomento per ogni pagina di documentazione. Per arrivare a questo risultato, mettiti dal punto di vista del tipo di utente per il quale vuoi scrivere. La documentazione che vuoi scrivere deve essere una risposta completa e sintetica ad una domanda precisa che ti farebbe il tipo di utente per il quale scrivi. Rifletti qualche minuto prima di scrivere! La tua documentazione sarà più facilmente utilizzabile!
Sto scrivendo un testo che ha bisogno di approfondimenti: posso inserire un link ad un'altra pagina?
No. Ti sconsiglio vivamente di farlo. L'ideale è che ogni pagina che scrivi sia autonoma (vedi la domanda precedente: il modello da seguire è "una domanda, una risposta", diciamo pure "one shot, one kill"!). Questo ha due vantaggi fondamentali:
- Potremo riutilizzare una stessa pagina in manuali diversi, per es. diretti a diversi utilizzatori, senza il pericolo che manchi qualche pagina richiamata dai link posti all'interno del testo.
- Chi aggiornerà la pagina, chiunque sia, potrà occuparsi solo del testo della pagina, senza preoccuparsi di andare a controllare se sono ancora valide le informazioni di pagine eventualmente collegate con link all'interno del testo.
Se hai bisogno di raccogliere assieme più pagine per ottenere un manualetto esaustivo su un certo argomento, vedi la domanda seguente.
Ho scritto parecchie pagine sparse, ma che si occupano di argomenti collegati: come faccio a riunirle in un indice logico?
Puoi creare una pagina in cui inserire (manualmente) i link alle tue pagine nell'ordine che preferisci. La pagina così creata diventerà l'indice di una mini-guida: per es., puoi creare una "Guida alla configurazione", "Guida per l'utente" e così via, che conterranno un indice gerarchico delle pagine pertinenti.
Altrimenti se avrai avuto la pazienza di classificare correttamente le pagine che hai creato, avremo anche il vantaggio di esportare automaticamente tutte le pagine classificate secondo una certa categoria con la funzione di esportazione del wiki, e questo ci servirà per inserire delle guide ad hoc in altri wiki.
Voglio cambiare il titolo di una pagina: come si fa?
Il cambio del titolo di una pagina è una procedura "antipatica" e rischiosa in un wiki. Ti consiglio invece di fare così:
- Crea la nuova pagina col titolo corretto.
- Copia il contenuto della pagina col titolo sbagliato e incollalo nella nuova pagina.
- Cancella il contenuto della vecchia pagina.
Posso caricare dei file?
Al momento si possono caricare immagini cliccando su "Carica un file" nel menù "strumenti" presente in ogni pagina sulla sinistra. Per linkare l'immagine si usa la stessa sintassi:
[[File:<nome_file>]]
Carica immagini che aiutino l'utente ad interagire con l'interfaccia o che mostrino ciò di cui stai parlando.
