Linee guida per i contenuti

Da Wiki di NetBSD Italia.

(Differenze fra le revisioni)
m
(Regole generali)
 
(3 revisioni intermedie non mostrate.)
Riga 11: Riga 11:
* Ogni articolo deve fare parte almeno di una categoria. Gli articoli privi di categoria verranno spostati e/o categorizzati dal team di NetBSD Italia.
* Ogni articolo deve fare parte almeno di una categoria. Gli articoli privi di categoria verranno spostati e/o categorizzati dal team di NetBSD Italia.
* Prima di apportare modifiche di grosse dimensioni è necessario informare la comunità tramite la pagina di discussione associata a quell'articolo.
* Prima di apportare modifiche di grosse dimensioni è necessario informare la comunità tramite la pagina di discussione associata a quell'articolo.
 +
* Evitare di trattare una versione specifica del sistema. A volte può risultare più utile (e meno dispendioso in termini di revisione degli articoli) indicare una determinata funzionalità o supporto come relativi alla versione in uso del sistema ed a tutte le versionisuccessive, anziché limitare tali caratteristiche alla versione in sé. Pertanto una frase come ''il LKM per tmpfs é disponibili su NetBSD >= 4.0'' è decisamente meglio di ''lo scrolling di wscons è disponibile su NetBSD 2.0''.
 +
* Qualora una determinata funzionalità, discussa in un articolo, sia stata rimossa in versioni successive del sistema o si è a conoscenza del fatto che questa verrà comunque rimossa in futuro, è necessario farlo presente (anche inserendo un'apposita nota) al fine di non spiazzare o confondere i lettori che visualizzano l'articolo in un periodo differente da quello in cui è stato effettivamente scritto.
== Scelta del titolo ==
== Scelta del titolo ==
Riga 41: Riga 43:
* I comandi d'esempio devono fare esattamente '''il minimo''' indispensabile per ottenere i risultati richiesti. Flag ''verbose'' come -v di {{man|pkg_add|1}} o di {{man|tar|1}} '''non''' vanno utilizzate.
* I comandi d'esempio devono fare esattamente '''il minimo''' indispensabile per ottenere i risultati richiesti. Flag ''verbose'' come -v di {{man|pkg_add|1}} o di {{man|tar|1}} '''non''' vanno utilizzate.
* Per i comandi in ''pipe'' inserire con criterio gli operatori ''';'''  (punto e virgola) e '''&&''' (doppia e commerciale). Utilizzare il primo qualora non sia necessario verificare la corretta terminazione del comando eseguito come argomento di sinistra e il secondo qualora questo controllo fosse necessario.
* Per i comandi in ''pipe'' inserire con criterio gli operatori ''';'''  (punto e virgola) e '''&&''' (doppia e commerciale). Utilizzare il primo qualora non sia necessario verificare la corretta terminazione del comando eseguito come argomento di sinistra e il secondo qualora questo controllo fosse necessario.
-
* Nel caso di modifiche a file di configurazione o altro, limitarsi a informare l'utente che si dovrebbe cambiare il contenuto di un file includendo i dettagli relativi alla modifica senza mostrare il comando di editing. Per modifiche statiche utilizzare l'editor ''inline'' {{man|1|sed}}.
+
* Nel caso di modifiche a file di configurazione o altro, limitarsi a informare l'utente che si dovrebbe cambiare il contenuto di un file includendo i dettagli relativi alla modifica senza mostrare il comando di editing. Per modifiche statiche utilizzare l'editor ''inline'' {{man|sed|1}}.
-
Se invece il comando è inserito all'interno del testo (non è quindi in rilievo) bisogna aggiungere dove possibile il collegamento alla relativa pagina di manuale, ma '''solo''' nel caso in cui questa sia presente nel [http://man.netbsd.org/ database ufficiale].
+
Se invece il comando è inserito all'interno del testo (non è quindi in rilievo) bisogna aggiungere dove possibile il collegamento alla relativa pagina di manuale, ma '''solo''' nel caso in cui questa sia presente nel [http://man.netbsd.org/ database ufficiale]. In caso contrario o nelle citazioni successive a quelle in cui si sia utilizzato il [[Template:Man]], formattare il nome del comando in corsivo come ''sed'' o ''sed(1)''; questo previene, all'interno dello stesso articolo, collegamenti che puntano alla stessa pagina.
==== Esempi ====
==== Esempi ====
Riga 94: Riga 96:
  '''NOTA''': questa è una nota da evitare
  '''NOTA''': questa è una nota da evitare
-
In quanto questo genere di formattazione è riservato ad altre tipologie di testo (vedi la sezione [[#Comandi|comandi]]).
+
In quanto questo genere di formattazione è riservato ad altre tipologie di testo (come i [[#Comandi|comandi]]).
== Menù ==
== Menù ==

Versione corrente delle 23:23, 17 feb 2010

L'intento di questa pagina è quello di stabilire dei criteri per l'organizzazione dei documenti all'interno del Wiki cercando di collocarli nelle giuste categorie e, qualora fosse necessario, creandone di nuove secondo i criteri qui descritti.

Indice

Regole generali

  • Le pagine non devono essere firmate: il nome di chi ha creato l'articolo e di chi ha, eventualmente, contribuito non và incluso a meno che non sia pertinente all'argomento
  • Considerazioni personali, commenti e quant'altro non sia strettamente correlato all'articolo o di rilevante importanza per la comprensione dello stesso è decisamente da evitare.
  • Qualora la dimensione del testo richiesto per la creazione di un articolo sia inferiore a una pagina completa, è opportuno optare per l'inclusione di una nuova FAQ piuttosto che di un nuovo articolo.
  • Utilizzare il testo '''WIP''' (Work in Progress) per marcare una sezione come incompleta.
  • Evidenziare frasi incerte includendo commenti preceduti dalla parola '''FIXME'''; per parti mancanti che dovranno essere scritte in seguito includere un commento preceduto dalla parola '''XXX'''.
  • I documenti non devono essere personalizzati. Generalizzare gli output rimanendo aderenti, dove possibile, all'originale.
  • Minimizzare l'uso di frasi in lingue straniere. L'ausilio di lingue diverse da quella italiana è da riservarsi esclusivamente per citazioni, output (ovviamente) e termini universalmente accettati.
  • Ogni articolo deve fare parte almeno di una categoria. Gli articoli privi di categoria verranno spostati e/o categorizzati dal team di NetBSD Italia.
  • Prima di apportare modifiche di grosse dimensioni è necessario informare la comunità tramite la pagina di discussione associata a quell'articolo.
  • Evitare di trattare una versione specifica del sistema. A volte può risultare più utile (e meno dispendioso in termini di revisione degli articoli) indicare una determinata funzionalità o supporto come relativi alla versione in uso del sistema ed a tutte le versionisuccessive, anziché limitare tali caratteristiche alla versione in sé. Pertanto una frase come il LKM per tmpfs é disponibili su NetBSD >= 4.0 è decisamente meglio di lo scrolling di wscons è disponibile su NetBSD 2.0.
  • Qualora una determinata funzionalità, discussa in un articolo, sia stata rimossa in versioni successive del sistema o si è a conoscenza del fatto che questa verrà comunque rimossa in futuro, è necessario farlo presente (anche inserendo un'apposita nota) al fine di non spiazzare o confondere i lettori che visualizzano l'articolo in un periodo differente da quello in cui è stato effettivamente scritto.

Scelta del titolo

Nome articolo

  • Le pagine relative a una determinata operazione (installazione, configurazione, etc.) dovrebbero avere un titolo chiaro che riassuma esattamente l'argomento trattato, ad esempio: Installazione di Samba, Installazione di Xorg modulare, etc.
  • Gli articoli che documentano un software partendo dalla sua installazione e concludendo con la verifica della corretta configurazione , elencando eventualmente alcune soluzione per la risoluzione di problemi comuni, dovrebbero avere un titolo che inizi col testo Messa appunto di/del seguito dal nome del software in questione. Nel caso in cui vengano trattati altri software in un unico articolo utilizzare un + come separatore, ad esempio: [[Messa a punto di Lighttpd + PHP + MySQL]].
  • Il titolo di un articolo avente un tono conversativo non troppo formale può essere arbitrario, purchè sia quanto più descrittivo possibile. Un esempio ben scritto di questo genere di articoli (da utilizzare come unità di riferimento) è Primi passi con NetBSD.

Sezioni e capitoli

Ogni sezione o capitolo dovrebbe rispecchiare quanto segue:

  • contenere un testo quanto più descrittivo e breve possibile.
  • essere in puro testo, ovvero senza:
    • collegamenti (interni o esterni);
    • variazioni di font (grassetto, corsivo);
    • nomi di file o percorsi;
    • caratteri estranei all'insieme [a-zA-Z0-9].

Formattazione

I documenti devono essere formattati secondo criteri ben precisi, rappresentati dalle seguenti regole:

Comandi

I comandi da eseguire su una shell, dal momento che sono la parte fondamentale di una procedura, è opportuno che vengano messi in risalto secondo dei criteri ben precisi.

  • Il comando deve iniziare con uno dei seguenti simboli
  1. cancelletto, #: se per funzionare correttamente necessità dei privilegi dell'amministratore di sistema;
  2. dollaro, $: se può essere eseguito da utente non privilegiato.
  3. percentuale, %: per enfatizzare il fatto che il comando in questione è specifico per csh e, con tutta probabilità, non funzionerà sulle shell Bourne-like. Nel caso in cui il comando necessiti dei privilegi di amministratore utilizzare comunque il simbolo cancelletto, #, specificando in modo evidente la shell da utilizzare (csh).
  • Il comando dev'essere formattato in base alle regole di MediaWiki che prevedono l'inserimento di uno spazio a inizio riga in modo da incorniciare il testo successivo.
  • I comandi d'esempio devono fare esattamente il minimo indispensabile per ottenere i risultati richiesti. Flag verbose come -v di pkg_add(1) o di tar(1) non vanno utilizzate.
  • Per i comandi in pipe inserire con criterio gli operatori ; (punto e virgola) e && (doppia e commerciale). Utilizzare il primo qualora non sia necessario verificare la corretta terminazione del comando eseguito come argomento di sinistra e il secondo qualora questo controllo fosse necessario.
  • Nel caso di modifiche a file di configurazione o altro, limitarsi a informare l'utente che si dovrebbe cambiare il contenuto di un file includendo i dettagli relativi alla modifica senza mostrare il comando di editing. Per modifiche statiche utilizzare l'editor inline sed(1).

Se invece il comando è inserito all'interno del testo (non è quindi in rilievo) bisogna aggiungere dove possibile il collegamento alla relativa pagina di manuale, ma solo nel caso in cui questa sia presente nel database ufficiale. In caso contrario o nelle citazioni successive a quelle in cui si sia utilizzato il Template:Man, formattare il nome del comando in corsivo come sed o sed(1); questo previene, all'interno dello stesso articolo, collegamenti che puntano alla stessa pagina.

Esempi

Questo è un comando che non richiede i privilegi d'amministratore:

$ comando --flag argomento argomentoN..

Questo è un comando che richiede i privilegi d'amministratore:

# comando --flag argomento argomentoN..

Questo è un comando per una shell csh-compatibile che non richiede i privilegi di amministratore:

% comando --flag argomento argomentoN..

Questo è un esempio di comando inserito nel testo non in rilievo:

[..]per installare un pacchetto dobbiamo servirci del tool pkg_add(1). pkg_add è..[..]

In caso di dubbi utilizzare il simbolo cancelletto (#) al fine di prevenire errori relativi ai permessi. Tuttavia, è buona norma evitare, se possibile, l'utilizzo di tale simbolo qualora non fosse strettamente necessario.

Infine se l'output generato dal programma è molto lungo e inutile omettere tutte le righe che non sono utili tramite dei [...], ad esempio:

$ dmesg
[...]
boot device: wd0
root on wd0a dumps on wd0b
root file system type: ffs
[...]

Percorsi e nomi

I percorsi e i nomi dei file dovrebbero essere formattati in corsivo al fine di distinguerli facilmente, ad esempio:

[..]Il file rc.conf, che si trova all'interno della directory /etc/, contiene..[..]

Inoltre, per un'ulteriore distinzione, le directory sarebbe opportuno terminarle sempre con uno slash finale (come nell'esempio precedente).

Variabili

Per quanto riguarda le variabili, come ad esempio ${EDITOR} devono rimanere come il testo normale. Ad esempio:

[..]Dopo aver impostato ${CVSROOT}, si deve specificare anche la variabile ${CVS_RSH}..[..]

Note

In determinate circostanze può risultare necessario l'inserimento di alcune note al fine di sottolineare dei concetti di rilevante importanza nel contesto in cui ci si trova. In questi casi è sufficiente far precedere il testo della nota dalla parola NOTA formattata in grassetto e seguita dal simbolo : (due punti) e dal testo della nota senza alcuna formattazione. Esempio:

NOTA: questa è una nota

Sono da evitare note come la seguente:

NOTA: questa è una nota da evitare

In quanto questo genere di formattazione è riservato ad altre tipologie di testo (come i comandi).

Menù

I menù di navigazione vanno "popolati" come segue:

  • il menù principale (titolo: menu) contiene le voci indispensabili per non perdersi durante la gestione dei contenuti, del wiki e per la fase di apprendimento dei concetti basilari (come quelli esposti all'interno della categoria fondamenti, ad esempio)
  • il menù delle sezioni (titolo: sezioni) contiene esclusivamente le sezioni disponibili all'interno della pagina principale (quelle in primo piano con le relative icone)
  • il menù strumenti (titolo: strumenti) contiene alcune delle cosiddette pagine Speciali. Nessun criterio stabilisce le voci da collocare al suo interno; l'unica costante è l'utilità secondo il punto di vista soggettivo degli amministratori del wiki.

L'aggiunta o la rimozione di un menù deve giustificare l'inserimento di un numero ragionevole di voci considerate irrinunciabili o, quanto meno, di importanza rilevante. Qualsiasi richiesta di modifica dei menù può essere effettuata aprendo una discussione nella pagina principale del wiki.

Collegamenti

Per saperne di più riguardo alla sintassi di questo wiki, prima di iniziare a scrivere documentazione è caldamente consigliato leggere la seguente documentazione:

Strumenti personali