Linee guida su voce e stile

Moltissime persone, tra cui professionisti IT e sviluppatori, leggono la documentazione di .NET sia per raccogliere informazioni su .NET che per usarlo nelle proprio lavoro quotidiano. L'obiettivo è creare una documentazione utile che accompagni il lettore. Le linee guida sono pensate per questo. La guida di stile contiene le indicazioni seguenti:

Usare uno stile colloquiale

Il paragrafo seguente è scritto in uno stile colloquiale, mentre quello successivo usa uno stile più accademico.

Stile appropriato

La documentazione deve avere uno stile colloquiale. Deve sembrare che si stia parlando con l'autore mentre si legge una delle esercitazioni o delle spiegazioni. L'esperienza deve risultare informale, colloquiale e informativa, come se i lettori stessero ascoltando l'autore mentre spiega loro i concetti.

Stile non appropriato

È possibile notare la differenza tra uno stile colloquiale e lo stile adottato in argomenti tecnici in cui si usa un tono più accademico. Queste risorse sono molto utili, ma gli autori hanno scritto tali articoli usando uno stile molto diverso rispetto a quello di questa documentazione. Leggendo una rivista accademica, si nota uno stile molto diverso e un modo di scrivere altrettanto differente. L'impressione è quella di leggere un argomento monotono scritto da un autore di poche parole.

Scrivere in seconda persona

Il paragrafo seguente usa la seconda persona, mentre quello successivo è alla terza persona. Scrivere in seconda persona.

Stile appropriato

Scrivi gli articoli come se parlassi direttamente al lettore, usando spesso la seconda persona (come in queste due frasi). Usare la seconda persona non significa usare sempre il "tu", ma scrivere direttamente al lettore e scrivere frasi imperative, dicendo al lettore quello che deve sapere.

Stile non appropriato

Un autore può scegliere di scrivere in terza persona. In tale modello l'autore deve trovare un pronome o un nome da usare quando si rivolge al lettore. Per il lettore, lo stile in terza persona potrebbe spesso risultare meno coinvolgente e la lettura sembrare meno interessante.

Usare la voce attiva

Scrivere gli articoli usando la voce attiva. Significa che,se si usa la voce attiva, il soggetto della frase esegue l'azione (verbo) di tale frase, mentre se si usa la voce passiva, la frase è strutturata in modo che il soggetto della frase subisca l'azione. Mettere a confronto questi due esempi:

Il compilatore ha trasformato il codice sorgente in un eseguibile.

Il codice sorgente è stato trasformato in un eseguibile dal compilatore.

La prima frase usa la voce attiva. La seconda frase è stata scritta usando la voce passiva. Queste due frasi sono un altro esempio dei due stili.

È consigliabile usare la voce attiva perché risulta più leggibile. La voce passiva è più difficile da leggere.

Scrivere per lettori che potrebbero avere un vocabolario limitato

Gli articoli sono indirizzati a lettori di tutto il mondo. Molti lettori non sono madrelingua inglesi e potrebbero non avere il vocabolario inglese di chi scrive.

I destinatari degli articoli sono tuttavia professionisti tecnici. Si presume quindi che abbiano conoscenze nel campo della programmazione e conoscano i termini tecnici di questo settore. Programmazione orientata agli oggetti, classe e oggetto, funzione e metodo sono termini familiari. Non tutti i lettori sono tuttavia laureati in informatica. Termini come "idempotente" necessitano probabilmente di una definizione qualora si vogliano usare, ad esempio:

Il metodo Close() è idempotente, vale a dire che può essere chiamato più volte e l'effetto sarà lo stesso come se fosse chiamato una volta.

Evitare il tempo futuro

In alcune lingue, il concetto di futuro è diverso rispetto all'inglese. L'uso del futuro rende difficoltosa la lettura. In più, se si usa il futuro, la domanda che ovviamente sorge è "Quando accadrà?". Quindi, se si dice "Sarà importante conoscere PowerShell", il lettore si domanderà ovviamente quando sarà importante. È invece meglio scrivere "È importante conoscere PowerShell".

Cos'è e a cosa serve

Quando si presenta al lettore un nuovo concetto, definire tale concetto prima di spiegare perché è utile. È importante che il lettore capisca cos'è prima di capirne i vantaggi o eventualmente gli svantaggi.