SDB:Howto
Situazione
Questo articolo SDB (database di supporto) spiega come scrivere articoli di tipo SDB.
Procedure
Gli articoli SDB sono scritti per fornire soluzioni ai problemi con openSUSE, ma anche per dare spiegazioni più dettagliate a certi *argomenti. Se riscontri dei problemi con openSUSE, SDB dovrebbe essere il primo posto in cui cercare una soluzione.
Un articolo di tipo SDB dovrebbe essere diviso nelle seguenti parti:
- Situazione
- Procedura
- Collegamenti
o
- Sintomo
- Causa
- Soluzione
- Collegamenti
Tieni sempre presente che - se possibile - gli articoli SDB dovrebbero descrivere sempre la soluzione più semplice ai problemi in oggetto. È anche desiderabile mostrare la via più facile per la soluzione usando la linea di comando o tramite la modifica dei file di configurazione. In questo caso, la sezione "Soluzione" dovrebbe essere divisa in diverse sottosezioni per semplificare e fornire informazioni più particolareggiate. Prima di scendere nello specifico della sintassi da usare, è possibile trovare qui un esempio da cui partire: (il template en:Template:SDB_article è disponibile per aiutare nella creazione di un nuovo articolo SDB)
Creare un nuovo articolo
Nel tuo web browser, inserisci il titolo del nuovo articolo subito dopo SDB: nella linea URL. Se l'articolo non esiste ancora, clicca su "Modifica" per crearlo e scriverlo.
Tutti gli articoli SDB devono assolutamente cominciare con SDB:, questo rende facile la loro ricerca e permette di costituire una separata sezione nel Wiki, più facilmente fruibile.
Traduzioni
openSUSE wiki supporta differenti lingue straniere. Se conosci qualche altra lingua oltre alla tua, traduci il tuo articolo, in modo da renderlo disponibile a più utenti possibili. Se invece non sei sicuro di avere una solida conoscenza di qualche altra lingua straniera, contatta pure con una e-mail la mailing list opensuse-wiki e chiedi a qualcuno di tradurre il tuo articolo.
Nel caso tu abbia tradotto un articolo, aggiungi i collegamenti "Interwiki" alla fine dei rispettivi articoli, per ogni traduzione fatta. Per esempio, nel caso tu abbia tradotto un articolo dal tedesco all'inglese, aggiungi alla fine dell'articolo tedesco:
[[en:SDB:<nome dell'articolo>]]
Alla versione inglese, aggiungi invece il seguente:
[[de:SDB:<nome dell'articolo>]]
Modificare articoli esistenti
Il namespace SDB è inserito nel nostro processo di revisione. Se tu modifichi un articolo, i cambiamenti che inserirai saranno prima verificati e poi resi disponibili a tutti gli utenti.
Categorie
Ogni articolo SDB dovrebbe essere accessibile attraverso la voce categorie. Puoi trovare una lista delle categorie disponibile qui: Categoria:SDB. Aggiungi le categorie alla fine dell'articolo:
[[Category:SDB:8.0|C]] [[Category:SDB:Network|C]]
La categoria è seguita dal carattere "barra verticale", o pipe, e dal primo carattere del titolo. Nell'esempio esposto sopra, l'articolo è chiamato "Changing NTP Servers", e cosi il carattere pipe è seguito da una "C".
Sintassi
Per favore leggi la pagina relativa alle nostre linee guida sullo stile del wiki per avere una panoramica riguardo a come formattare il contenuto dell'articolo.
Stile
Come rivolgersi ai lettori
Gli articoli tedeschi SDB per fare un esempio, dovrebbero essere scritti usando la forma "Sie", che è quella che si applica nella documentazione tecnica. Se questo principio si applica anche alla tua lingua, nella stesura dell'articolo usa la corrispettiva forma cortese. Gli autori in lingua inglese, naturalmente non hanno questo tipo di problema ;-).
Terminologia da utilizzare usando le lingue straniere
In lingue diverse dall'inglese, qualche volta è difficile tradurre senza usare gli originali termini tecnici inglesi. È importante in generale, scrivere in modo da rendere comprensibile e utilizzabile l'articolo al più ampio gruppo possibile di utenti degli articoli SDB. È importante non provare a fare delle traduzioni quando gli originali termini inglesi sono comunemente compresi e usati nella lingua di destinazione. Un buon compromesso è rappresentato da usare entrambi, lingua in uso e termine inglese, come mostrato in questo esempio in lingua tedesca: "gehen Sie auf die zweite console (Kommandozeile) mit STRG-ALT-F2"
Calma!
Anche se l'uso della shell qualche volta può sembrare semplice, specialmente per te,ricorda di tenere bene in mente gli utenti Linux alle prime armi e mentre scrivi, spiega come un problema può essere risolto con YaST2 o altri strumenti.
Un buon articolo SDB dovrebbe descrivere ogni singolo passo per ottenere il risultato, oppure indicare almeno un link ad un altro articolo dove è presente una specifica spiegazione a riguardo. Cosi, non scrivere:
In /etc/inittab, cambia il runlevel di default portandolo a 3.
ma:
Accedi ad una sessione come utente root (superutente), poi apri il file /etc/inittab con un editor a tua scelta (es.: vi o pico). Modifica la linea id:5:initdefault: cambiandola in id:3:initdefault: cosi il sistema non si avvierà più con l'interfaccia utente grafica.
Quando si scrive, è utile ricordarsi che molti nuovi utenti Linux usano solo da poco tempo openSUSE.
Mantenimento dell'articolo SDB
È spesso necessario modificare gli articoli SDB quando vengono rilasciate nuove versioni di openSUSE, o anche scriverne di nuovi, se i cambiamenti contenuti nelle nuove distribuzioni sono fondamentali e divergenti dalle versioni precedenti. Sottolineiamo quindi l'importanza di fare la manutenzione dei propri articoli SDB. Cosi, per esempio, se ti accorgi che il tuo articolo, nei contenuti, non è più in linea con l'ultima versione di openSUSE, modificalo cambiando la linea indicante la versione.