Aiuto:Prima di iniziare

Da Guide@Debianizzati.Org.
Vai alla navigazione Vai alla ricerca

Prima di iniziare a scrivere o modificare una guida è opportuno conoscere poche e semplici convenzioni in modo che il contenuto del Wiki cresca in maniera omogenea e quindi più facile da leggere, per tutti.
Queste convenzioni riguardano la struttura delle pagine e dell'intero Wiki: se avete dubbi o domande potete utilizzare la pagina di discussione relativa a ciascuna guida oppure aprire una discussione sul forum nella sezione ""Guide@Debianizzati.Org".

Linee guida su come contribuire al Wiki

Sommario

Versioni compatibili

Il template "Versioni compatibili" va inserito all'inizio di ciascuna pagina affinché si capisca immediatamente a quali versioni di Debian fa riferimento la guida. Consultare questa pagina per ottenere istruzioni specifiche sul suo utilizzo.

Categorie

Ciascuna guida deve far parte di una o più categorie per essere indicizzata e permetterne una più facile ricerca e individuazione. Ricordarsi pertanto di inserire, in fondo alla guida, il tag [[Categoria: nome_della_categoria]] per ciascuna categoria di cui la guida andrà a far parte.

Convenzioni sulla sintassi

  1. Tutte le volte che riportate l'output di un comando, un pezzo di un file di configurazione o in genere dei dati ASCII, racchiudeteli in un riquadro (racchiudendo tra <pre> e </pre>).
  2. Se riportate un comando usate come primo carattere "$" se il comando deve essere lanciato da utente normale e "#" se il comando deve essere lanciato da root. Lasciate anche uno spazio dopo questo carattere, in modo che il comando non risulti attaccato al $ o # e quindi poco leggibile.
  3. Quando dovete inserire all'interno del corpo del testo i seguenti elementi:
    • percorsi di file o cartelle;
    • nomi di file;
    • comandi, opzioni di comandi, singole stringhe e/o direttive dei file di configurazione;
      racchiudeteli tra i tag <code> e </code>.
  4. Non utilizzare i titoli di primo livello ("= .... =") all'interno delle guide. Questi sono adibiti a formattare il titolo dell'intera guida.
  5. Se possibile, non utilizzare i sotto-titoli di terzo livello ("==== .... ====") o più piccoli: indirizzarsi piuttosto sugli elenchi. Questo è dovuto a motivi di ordine dell'indice oltre al fatto che la loro presenza non produrrebbe alcun vantaggio in termini di leggibilità della guida.

Convenzioni sullo stile

  1. Non utilizzare i titoli di primo livello ("= .... =") all'interno delle guide. Questi sono adibiti a formattare il titolo dell'intera guida.
  2. Se possibile, non utilizzare i sotto-titoli di terzo livello ("==== .... ====") o più piccoli: indirizzarsi piuttosto sugli elenchi. Questo è dovuto a motivi di ordine dell'indice oltre al fatto che la loro presenza non produrrebbe alcun vantaggio in termini di leggibilità della guida.
  3. Dividete in maniera logica la guida in sezioni, sottosezioni (e, se necessario sotto-sottosezioni). In questo modo si sfrutterà meglio la potenza di MediaWiki che creerà automaticamente un indice iniziale che renderà molto più facile la navigazione nella vostra guida.
  4. Usate, quando necessario, i vari elementi di formattazione (descrizioni, riquadro di warning, esempio ecc.): la guida risulterà più leggibile.
  5. Cercate di rendere leggibile e pulito il codice della pagina, evitando ad esempio di lasciare tante righe vuote consecutive.

Interconnessione dei contenuti

Cercate il più possibile di inserire link ad altre pagine del Wiki in modo da aumentare le interconnessioni, rendere più facile la ricerca delle informazioni ed evitare inutili ripetizioni in più di una guida.
Non è necessario che le pagine verso cui si creano i link debbano esistere (in questo caso il link resterà di colore rosso); la loro creazione può essere successiva da parte dello stesso autore o di altri. In entrambi i casi la presenza di link ad altri contenuti del Wiki renderà la guida stessa più completa, leggibile e facile da aggiornare.

Evoluzione delle guide

Le guide seguono un percorso (idealmente) simile a quello seguito dai pacchetti Debian nelle tre distribuzioni. Si distinguono infatti tre fasi per una guida:

  • Stub: una guida è in questo stato se è ancora incompleta. Queste guide sono caratterizzate dal seguente box iniziale il cui inserimento (e rimozione) sarà prevalentemente compito dell'autore della pagina.
    Vi preghiamo, come segno di rispetto per coloro che leggeranno la vostra pagina, di non lasciare la guida in stato di "Stub" per troppo tempo.
  • Guida completa: la guida si ritiene conclusa e gli argomenti di cui tratta possono essere letti senza che vi siano avvertimenti sulla loro completezza. Le guide di questo tipo non hanno nessun segno particolare. Le guide complete sono state terminate dall'autore iniziale e cercano una sorta di verifica da parte della comunità.
  • Guida Debianized: è il terzo e ultimo livello raggiungibile da una guida sul Wiki. Una guida di questo tipo ha raggiunto la sua piena maturità essendo stata verificata e corretta anche da più di una persona nella community. Nell'indice le guide Debianized sono facilmente individuabili da una swirl: Swirl.png. Tutte le guide sul Wiki possono diventare Debianized una volta ricevuto un sufficiente feedback dalla comunità.

Se leggi una guida e verifichi la sua correttezza, utilizza per favore il template Autori in modo da tenere traccia della maturità della guida.

Con questi piccoli accorgimenti che richiedono un piccolo aiuto da parte della community, speriamo di poter tracciare e mantenere lo "stato di salute" delle guide, sperando che un numero sempre maggiore di esse diventi Debianized ;-).

Pagine protette

Alcune pagine del Wiki sono protette, cioè un normale utente non può modificarle anche se registrato. Le pagine protette sono pagine di presentazione del progetto, pagine di licenza o pagine tecniche del Wiki. In nessun caso un articolo di documentazione riguardante Debian GNU/Linux verrà resa protetta. Se trovate una pagina protetta che, a vostro avviso, andrebbe resa aperta alla modifiche di tutti, per favore, segnalatelo agli amministratori.

Consigli grammaticali

Prima di salvare una guida è consigliato controllare la presenza di eventuali errori grammaticali o sintattici. Questo può essere fatto, ad esempio, sfruttando il controllo ortografico presente all'interno di molti editor o del browser che si sta utilizzando oppure utilizzando "aspell":

$ aspell check nomefile

Di seguito vengono riportati gli errori grammaticali più comuni che possono essere commessi quando si scrive una guida.

  1. Uso della punteggiatura

    Tutti i segni di interpunzione (virgola, punto, punto e virgola, punto esclamativo, ecc.) seguono direttamente la parola che li precede, senza spazi, e vanno separati dalla parola successiva con uno spazio. Non fanno eccezione i punti alla fine di un periodo. Es. "L'italiano, il francese e lo spagnolo sono lingue neo-latine."
    [...]
    Le parentesi di apertura hanno uno spazio che le precede mentre la parola successiva è attaccata ad esse. Il contrario è normalmente vero per le parentesi di chiusura, mentre non va messo alcuno spazio tra queste ed eventuali segni di punteggiatura. Es. "Esempio (dell'uso) di parentesi." In particolare, la punteggiatura del testo circostante non va inserita all'interno delle parentesi ma va posta dopo la parentesi di chiusura. Es. "Altro esempio (dell'uso di parentesi)."

  2. Uso delle maiuscole

    Mentre in inglese è convenzione porre tutte le lettere iniziali delle parole componenti un titolo in maiuscolo, in italiano ciò è considerato errore, in quanto solo la prima parola usa l'iniziale maiuscola.
    Ricorrere, inoltre, alla lettera maiuscola iniziale per le parole facenti parte della terminologia tecnica che si riferiscono a programmi, sistemi operativi o kernel (Debian, Linux, Samba, Wheezy, etc.)

  3. Accenti

    È da considerarsi errore l'uso di una vocale seguita da un apostrofo «'» o da un apice inverso «`» per simboleggiare una vocale accentata. Se la codifica lo consente, vanno sempre impiegati i simboli appositi, sia per le minuscole che per le maiuscole.
    Nell'ambiente X11 usato sui sistemi UNIX, le maiuscole accentate sono ottenibili usando il tasto BlocMaiusc insieme agli stessi tasti usati per le minuscole.
    Le vocali "a", "i" e "u" possiedono solo una possibile pronuncia e quindi vanno sempre poste con l'accento grave ("à", "ì", "ù"). La vocale "o", invece, può essere sia aperta che chiusa ma, poiché non esistono parole tronche che terminano per "o" chiusa, l'accento alla fine della parola è sempre grave ("ò"). In generale, è convenzione comune in editoria utilizzare esclusivamente l'accento grave sulle vocali "a", "i", "o" e "u".
    Per la vocale "e" la situazione è più complicata: normalmente va usato l'accento grave ("è") ma in alcuni casi va usato quello acuto ("é"): "perché", "affinché", "poiché" (in generale tutti i vocaboli che terminano in "ché"), "né", "sé".

  4. Acronimi

    Gli acronimi e gli acrostici vanno scritti in maiuscolo (GNU, USB, BIOS, PC, DVD, KDE, etc.) in quanto sono parole costituite da iniziali di altre parole o frasi.
    Prestare attenzione soprattutto quando li si utilizzano all'interno dei titoli di una guida.

Leggere anche Regole per la buona traduzione, a cura di E.Aina

Bozze

Per chi vuole fare esperienza con la sintassi del Wiki prima di creare una guida o modificarne una esistente, sono possibili diverse strade:

  1. Utilizzare la sandbox appositamente dedicata a prove, esperimenti e quant'altro
  2. Creare una pagina nel namespace del proprio utente (vedere anche come creare una bozza)
  3. Lavorare su una installazione in locale di Mediawiki