È irragionevole scrivere la documentazione dell'utente nello stile di un libro tecnico?

Question

È irragionevole scrivere la documentazione dell'utente nello stile di un libro tecnico?

#1 da (7 voti)
#2 da (3 voti)

7

Dimmi se ti sembra familiare:

something something something... as seen in figure 1-1 on the next page...

In praticamente tutti i libri che ho letto sulla programmazione. Così quando stavo scrivendo un piccolo opuscolo didattico su come usare un software in-house, che aveva le immagini dello schermo su cui l'utente si trovava in quel determinato passo, scrissi qualcosa del tipo "Lo schermo che appare sembra quello mostrato nella figura 1-1 sotto. "

Ma sto pensando: sono abituato a quello stile di scrittura, ma se il mio pubblico di destinazione è la "persona media" saranno confusi?

Quindi, più in generale, esistono pratiche comuni nei libri tecnici che dovrebbero essere evitate quando si scrive la documentazione per le persone comuni?

documentation writing

posta Steven Evers 20.10.2010 - 23:55

fonte

2 risposte

Leggi altre domande sui tag documentation writing

Progettazione dell'API REST: più chiamate o singola chiamata all'API Paginazione con API

score 7 · Answer 1

Se vuoi una risposta migliore alla tua domanda e un vero risveglio per quanto bene scrivi manuali didattici, consegna la signora alla scrivania le tue istruzioni e veglia su di lei mentre cerca di seguirla. Non interporre; fai finta che non ci sia. Chiedile di pensare ad alta voce. Prendi un sacco di note. Pronto per essere scioccato.

Torna indietro e riscrivi le istruzioni con tutti i feedback che hai ricevuto.

Almeno con i romanzi rosa, sai chi sta sbattendo chi. Le nostre istruzioni sono raramente chiare.

score 3 · Answer 2

Ci sono molti libri che descrivono stili e danno consigli sulla scrittura tecnica, ma quando pubblichiamo un libro, penso che sia una decisione dell'editore, su quante immagini avrà (le immagini influenzano i costi di pubblicazione), e che può anche influenzare in qualche modo il tuo stile di scrittura (se farai riferimento alla Figura 1-1 più volte, o se apparirà sempre sotto il testo, come in un tutorial).

Ad esempio, i libri che trattano i corsi di strumenti CAD spesso scelgono, per chiarezza e facilità d'uso, il secondo approccio (perché l'utente non vuole capovolgere pagine tutto il tempo, ma seguire il processo di generazione di un progetto, per esempio).

I libri di programmazione, da quello che ho visto più spesso seguono il primo esempio. Poiché le immagini di solito servono solo come aiuto per il testo, l'utente otterrà la maggior parte delle informazioni dal testo stesso. Pertanto, il riferimento a una figura più volte è accettabile.

Spero che questo abbia un senso ...