Ivan Tarozzi ha scritto:
> Ho appena creato un nuovo documento, che va a integrare quello già
> inserito (Troubleshooting eeePC) e descrive un po' anche la sequenza di
> boot del client.
>
> Sono stato volutamente molto sintetico (magari dando per scontato un po'
> di cose relative ad un bottstrap su PC) e ho cercato di limitare al
> massimo l'uso di tecnicismi troppo spinti (per quanto possibile
> dall'argomento trattato)
>
> Non trattandosi di traduzioni ma di articoli creati attingendo da un mix
> di conoscenze personali, manualistica ltsp e risorse internet gradirei
> riceve un vostro feedback soprattutto per quello che riguarda la
> terminologia, la chiarezza espositiva e la comprensione degli step
> pratici per raggiungere il risultato.
>
> Premesso che ovviamente tutto è migliorabile e che sicuramente alcuni
> troveranno la descrizione troppo semplicistica o poco approfondita, mi
> interessava un po' tarare il tiro soprattutto in ottica futura.
>
La completezza non è mai sintetica.
In compenso la sintesi è spesso più comunicativa.
Il giusto bilanciamento è più un'arte che una scienza.
Nel nostro caso, l'obiettivo primario è la comprensibilità.
Come indirizzo strategico direi di iniziare trattando i vari argomenti
sì in modo accurato e corretto, ma puntando alla massima comprensibilità
(compatibilmente con il contesto oggettivamente tecnico).
Lo scopo è quello di rendere i documenti accessibili a quante più
persone è possibile.
Non siamo guru e non scriviamo per guru (che comunque non ci leggerebbero).
Stiamo indagando un argomento tecnico, per capirlo e, se possibile, per
renderlo più comprensibile ad altri.
In questo senso, documentando la nostra indagine possiamo adottare
alcuni accorgimenti che facilitino la lettura e che rendano i contenuti
praticabili anche da persone non particolarmente esperte.
Va da sé che questi accorgimenti comportino più lavoro - lavoro noioso
per giunta - per i redattori.
Esempi:
- evitare contrazioni abbreviazioni e contrazioni arbitrarie dei nomi,
ad es. acronimi che non siano già consolidati.
(sì: "LTSP"; no: "TC", sì: "Thin Client", sempre per esteso).
- dove possibile, dare una spiegazione sintetica dei termini o dei
concetti tecnici più difficili oppure linkarli ad una pagina che li
documenti o li spieghi (es. un'altra pagina del wiki LTSP oppure
wikipedia).
Come criterio: linkare almeno la prima ricorrenza del nome oppure la
ricorrenza più importante nella pagina.
- pubblicare sempre in modo esplicito i comandi e le operazioni usati,
anche quelli più ovvi.
Es. NO:
Aprite il file pinco_pallino e modificate l'"opzione b" in "opzione c".
Se volete potete commentare l'opzione b e aggiungere l'opzione c.
Dopodiché accedete alla directory...
Es. SI:
Accedete alla console (link)
(se il documento lo richiede - ad es. istruzioni per maestre di scuola)
Aprite il file pinco_pallino:
sudo gedit /dirX/pinco_pallino
# file pinco pallino
istruzione 1
opzione a
opzione b
Modificate l'"opzione b" in "opzione c":
# file pinco pallino
istruzione 1
opzione a
opzione c
Se volete, potete aggiungere l'"opzione c" e "commentare" (parola
linkata a spiegazione) l'"opzione b", aggiungendo il carattere # ad
inizio riga e lasciadola nel file per eventuali ripensamenti futuri.
# file pinco pallino
istruzione 1
opzione a
# opzione b
opzione c
Al termine salvate il file (Ctrl+s).
Dopodiché accedete alla directory...
C'è una differenza abissale nello spazio occupato, ma nel secondo caso
anche un neofita sarà in grado di applicare le istruzioni.
Questo non significa spiegare ogni volta tutto da zero.
Con un po' di link alla tanta letteratura esistente e con un po' di buon
senso è possibile produrre documenti equilibrati.
> In ogni caso lo strumento del wiki nasce proprio per condividere
> documentazione e permettere agli utenti di
> migliorare/correggere/integrare i contenuti, quindi non fatevi scrupoli.
>
>
> Proprio su quest'ultimo punto volevo un chiarimento da Joris (o comunque
> dal direttivo):
> Se si riscontrassero errori o integrazioni nei documenti, come
> preferisci che agiamo? modifichiamo direttamente (con cognizione di
> causa) il documento o notifichiamo la cosa a chi ha scritto
> inizialmente? Personalmente, se non si crea troppo anarchia, preferirei
> la prima ipotesi (...) però questa è solo la mia idea.
>
Ad istinto, misurando con realismo l'ampiezza del wiki che stiamo
sviluppando e il numero di partecipanti, prediligerei una gestione
snella e poco burocratica.
Per cui, andrei con interventi diretti, a patto che siano guidati da
cognizione di causa e da rispetto nei confronti degli autori originali.
Eventualmente segnalerei o concorderei con agli autori solo cambiamenti
sostanziali.
Tra l'altro, l'opzione "monitor this page" (l'occhio in alto a destra
della pagina wiki) disponibile agli editori autorizzati consente di
attivare/disattivare la segnalazione automatica via e-mail delle
eventuali modifiche alla pagina.
Tuttavia, considerando che esistono già esperienze strutturate e ormai
ben collaudate, per non peccare di presunzione sono andato a leggermi
cosa facciano su wikipedia.
Qualche spunto:
http://it.wikipedia.org/wiki/Categoria:Linee_guida
http://it.wikipedia.org/wiki/Wikipedia:Ignora_le_regole
http://it.wikipedia.org/wiki/Wikipedia:Wikiquette
E' un lavoro in divenire, nel quale tutti abbiamo da imparare.
Bello, no?
Joris
Attachment:
signature.asc
Description: OpenPGP digital signature