Quali concetti sono pertinenti per pianificare una strategia di "documentazione per l'utente finale"?

Naviga le tue risposte
5

Sto scrivendo un sacco di software e sento che scrivere una buona documentazione è molto difficile. Poiché non sono a conoscenza di alcuna teoria strutturata sulla documentazione del software, ho iniziato ad organizzare le mie conoscenze in questo campo e spero che questo mi aiuterà a scomporre le informazioni in unità sensibili e ad organizzare la documentazione in modo efficiente.

Per prima cosa vorrei fare una lista completa di concetti rilevanti, che esaminerò in altre domande.

Quali concetti sono utili o rilevanti quando si descrive la documentazione dell'utente? In che modo questi concetti interagiscono tra loro? C'è qualche metodologia che posso usare per analizzare il mio software e ideare una strategia di documentazione pertinente?

Ho identificato i seguenti concetti:

  • Categorie di informazioni ricette simili ("come faccio a ...?"), riferimenti (come le pagine man di UNIX) o conoscenza esperta .

  • Ruolo utente come utente normale, utente avanzato, amministratore di sistema e qualsiasi altro ruolo definito dal sistema come responsabile della sicurezza, responsabile dati, ecc.

  • Medio come un manuale cartaceo, guida contestuale, wiki modificabile.

Questi concetti interagiscono l'uno con l'altro e portano a una serie di domande: quando è utile scrivere un manuale per ogni ruolo? Cosa dovrebbe andare nelle copie cartacee e cosa nel riferimento on-line? Quando è utile eseguire una wiki raccogliendo "ricette"? Con questi esempi, spero di poter fornire utili spiegazioni su ciò che capisco sotto "concetto" e "interazione" nelle mie domande.

    
posta Michael Le Barbier Grünewald 03.10.2013 - 17:50
fonte

1 risposta

2

Qualsiasi strategia per la fornitura di documentazione per l'utente finale si troverà a capofitto nella seguente legge universale della natura: 

People don't read.

Presumo che, nel tentativo di fornire documentazione per l'utente finale, si desideri fornire un valore aggiunto al cliente, sotto forma di una migliore comprensione del prodotto software. Ci sono diversi modi per farlo. Di gran lunga il modo migliore è 

Write the software so that it can be understood without any documentation.

In caso contrario, ci sono un certo numero di altre strategie che puoi utilizzare. Il metodo tradizionale di scrivere un manuale è certamente un modo, ma che dire:

  1. Tutorial video
  2. Guide di avvio rapido
  3. Procedure dettagliate

Hai mai acquistato un mobile da Ikea o uno di quei negozi online e l'hai assemblato seguendo le istruzioni del kit? Come è stata quell'esperienza? Se ne hai fatto uno di recente, potresti aver notato che ora consiste principalmente di immagini, con poche parole. Perché? Perché le persone non leggono e, come si suol dire, un'immagine vale davvero più di mille parole.

Una volta ho lavorato per una società che ha lottato con questo. La gente chiamerebbe il supporto invece di leggere il manuale. Come lo abbiamo finalmente risolto? Con diverse presentazioni di PowerPoint che erano pagine dopo pagina semplicemente passegiando il cliente attraverso ogni schermata, menu a discesa e casella di controllo. Ci sono voluti circa quattro mesi per fare tutto, ma i nostri clienti li adoravano. Preferivano di gran lunga i PowerPoint a qualsiasi altra forma di documentazione che gli abbiamo dato.

Anche le esercitazioni video sono buone, ma il problema è difficile da realizzare e sono difficili da usare; devono essere molto brevi, perché non sono accessibili a caso come un manuale; devi guardare tutto. Ma sono fantastici per ottenere la disposizione del software, per così dire.

Infine, scrivi un manuale se hai bisogno di una guida di riferimento (non un how-to). Ecco a cosa servono i manuali.

    
risposta data 25.11.2013 - 00:02
fonte

Leggi altre domande sui tag

Problema nella comprensione dell'algoritmo di TAOCP "Molteplici permutazioni in forma di ciclo" Controllo delle versioni del flusso di lavoro