Come scrivere una guida in Aduteca


#1

##Guida di stile per la documentazione
Questa guida si pone come punto di riferimento per tutti i collaboratori e amici di Adunanza per la redazione di documentazione per l’AduTeca.

Seguite questi suggerimenti per rendere i documenti contenuti nell’aduteca coerenti tra loro per forma e struttura. Le guide create saranno in tal modo fruibili, di facile lettura e comprensione da parte degli utenti.

##Regole generali
Una buona guida deve essere:

  • Chiara :esprimere i concetti in modo semplice.
  • Concisa: deve essere orientata all’uso immediato: il wiki non è un’enciclopedia.
  • Completa: deve descrivere gli aspetti più importanti di ciò che costituisce l’oggetto della guida stessa

L’utente che compila la guida deve:

  • Scrivere in modo impersonale: non rivolgersi mai direttamente al lettore, restando sempre neutrali.
  • Preferire un’esposizione sintetica: la prolissità mette a dura prova l’attenzione del lettore e può pregiudicare la comprensione dei concetti.
  • Scrivere in modo neutrale: evitare commenti personali, umoristici o sarcastici che possono distrarre l’utente.

###A chi scrivere

È importante, quando si scrive una guida, pensare a chi è rivolta; quali informazioni possono essere necessarie e anche come queste informazioni devono essere presentate.

Gli utenti solitamente usano le documentazione per avere una risposta a una specifica domanda, non leggono la documentazione per divertimento, è quindi necessario cercare di dare delle risposte chiare e precise a queste domande.

  • Nuovi utenti

I nuovi utenti solitamente fanno riferimento alla documentazione o ai manuali per cercare delle risposte precise. In questo caso è utile presentare le informazioni in base all’attività da svolgere, utilizzando gli elenchi numerati per descrivere un’azione alla volta.

  • Utenti esperti

Gli utenti esperti solitamente utilizzano le guide o la documentazione come riferimento, è quindi utile che la guida sia abbastanza completa e ben organizzata nei suoi paragrafi.

##Regole di compilazione e Struttura di una guida

Colori

Un nuovo plugin installato (aprile 2017) ha aumentato le funzioni e i tasti di formattazione sull’editor, tra cui la possibilità di aggiungere dei colori.
Si raccomanda di usare il colore rosso (hex #ff0000) solo ed esclusivamente nei titoli dei paragrafi se necessario, ma nessun altro colore nel testo della guida (a meno che non ci siano degli avvisi -warning- che l’utente deve assolutamente leggere).

Non vogliamo creare delle guide “arlecchino” che distraggano gli utenti dalla lettura!

Titolo

I titoli devono essere sintetici: meglio utilizzare poche parole chiave. Dovendosi tradurre in link non deve contenere caratteri particolari [→ es.:/()_- ]

Testo

  • La lingua utilizzata per scrivere la documentazione è l’italiano.

  • La guida deve essere scritta in forma chiara e lineare. Evitare l’uso di sottolineature o di grassetto o quantomeno limitarlo ai casi strettamente necessari.

  • Se l’esposizione è particolarmente lunga è consigliabile ordinare i passi descritti utilizzando lo strumento dell’elenco puntato .

  • Evitare l’uso di emoticon o faccine.

Paragrafi

E’ data la possibilità di suddividere il documento in paragrafi in base agli argomenti trattati:

  • usare il livello “Intestazione” uno o due per intitolare paragrafi principali;
  • usare il livello “intestazione” due o tre per i sotto-paragrafi usando dei titoli specifici per ogni sotto-paragrafo;

Esempi di sintassi per l’heading:

#Testo di prova (intestazione 1)
##Testo di prova (intestazione 2) 
###Testo di prova (intestazione 3)

I risultati saranno:

#Testo di prova (intestazione 1)
##Testo di prova (intestazione 2)
###Testo di prova (intestazione 3)

Si possono avere fino a 6 livelli di intestazione ma generalmente basta utilizzare i primi due o tre.

Per scrivere i titoli dei paragrafi, seguire queste regole:

  • non scrivere mai le parole dei titoli con tutte le iniziali maiuscole: non è forma italiana corretta;
  • i titoli devono essere sintetici ed è consigliabile utilizzate poche parole chiave

Riferimenti ad altri documenti

Per semplificare il lavoro di scrittura, all’interno di una guida è possibile (e raccomandato) fare riferimento alle altre guide presenti nel wiki.
I link possono essere estesi oppure di collegamento usando l’apposito tasto

Esempio di link esteso

Esempio di collegamento ad un link
Aduteca

Immagini

All’interno delle guide è possibile caricare delle immagini, screenshot, delle applicazioni o riguardo l’argomento trattato, solo se queste sono necessarie alla semplificazione della guida attraverso l’uso di un esempio visivo.

Le immagini non vanno usate per abbellimento visivo o per riempire una pagina.

Tenere a mente queste regole:

  • gli utenti devono scorrere la pagina per passare al successivo blocco di informazioni, le immagini possono rallentare la lettura;
  • le immagini vanno mantenute aggiornate con i nuovi rilasci dell’applicazione;
  • catturare solo la finestra dell’applicazione cercando di evitare lo sfondo del desktop;
  • usare un nome utente fittizio, soprattutto se vengono catturate immagini del terminale.
  • utilizzare il watermark adunanza.net sulle immagini (se queste ultime non sono prese, per esempio, da altri siti).
  • per le immagini usare il formato PNG o JPEG.

Per caricare le immagini sarà sufficiente premere il tasto .

Sezioni

Inserire la guida nella giusta sottosezione è fondamentale per gli utenti che cercano aiuto sul forum.

Per la stesura della guida è utile usare la sottosezione #aduteca:lavorazione accessibile solo agli utenti di livello 2 o superiore. In questo modo una guida incompleta, in lavorazione o in attesa di revisione non sarà accessibile ai nuovi utenti del forum.
Quando si ritiene la guida pronta per la pubblicazione è buona norma avvisare un membro dello Staff che provvederà a spostare la guida nella giusta sottosezione dell’Aduteca.


Le guide in Aduteca diventano automaticamente wiki senza l’intervento dello Staff.
Questo significa che ogni utente può modificarle, aggiornarle o migliorarle. Per fare ciò basta cliccare sull’icona della matita che compare in alto a destra all’inizio della guida stessa per poter apportare le modifiche necessarie sia al testo sia alla formattazione.

Un esempio di guida wiki

In caso di dubbi non esitate a contattare un qualsiasi membro dell’AduTeam per avere chiarimenti in merito alle guide o alla loro corretta ubicazione nel forum.

Buon lavoro a tutti!

##Fonte:
AduTeca- una questione di stile - AduTeca.pdf (2.1 MB)


Definizione della categoria AduTeca