Esistono due tipi di documentazione di base: guida per l'utente e documentazione di riferimento .
(Alcune aziende riconoscono anche la panoramica come un tipo separato, vedi sotto).
Documentazione di riferimento elenca, diligentemente e accuratamente, l'intera interfaccia pubblica del prodotto: cosa significano ciascun parametro e parametro, quale input è considerato valido e cosa viene restituito in ogni caso ecc.
- Nota la parola interfaccia pubblica : il suo obiettivo principale è specificare quali dettagli del comportamento osservato sono ufficialmente garantiti e quindi possono essere utilizzati. (Affermando o sottintendendo per omissione che tutto il resto è dettagli dell'implementazione, soggetto a modifiche e interruzione senza preavviso.)
- Nota anche la parola "interezza". Il punto vendita principale di un riferimento è la sua completezza. Se non è nel riferimento, non esiste (ufficialmente). Se ho letto un riferimento su un argomento, posso essere certo che ora so tutto su quell'argomento e non ci saranno brutte sorprese.
- Quindi, anche se un riferimento può essere utilizzato come materiale didattico, il suo caso d'uso principale è quello di colmare le lacune.
Poiché i principi di progettazione si manifestano direttamente nella struttura e nell'organizzazione dell'interfaccia pubblica, una documentazione di riferimento può contenere sezioni di panoramica su parti e aspetti dell'interfaccia e comportamento del prodotto prima di elencarne i dettagli (se non altro per evitare di ripeterle nelle voci per singole API).
- Anche in questo caso, l'attenzione è rivolta all'interfaccia pubblica, quindi le spiegazioni si concentreranno sui dettagli visibili all'utente, fondamentali per comprendere l'organizzazione e il comportamento del prodotto, e i tecnicismi non importanti possono essere omessi o fatti a mano.
Lo scopo di
A Guida per l'utente è piuttosto quello di dimostrare come gli autori del prodotto prevedono l'utilizzo dell'interfaccia pubblica per risolvere problemi pratici e / o loro classi: schemi di utilizzo previsti, problemi generali tipici e soluzioni proposte (problemi locali ad API specifiche sembra piuttosto appartenere alle loro voci di riferimento).
Una guida per l'utente è intenzionalmente incompleta, fornendo solo la "grande immagine" e i puntatori chiave e lasciandola al riferimento per elaborare i dettagli.
La guida per l'utente può anche avere un testo di panoramica, ma il punto focale della panoramica qui è il pattern di utilizzo: che cosa è supposto essere chiamato dopo quello che, da quali posti ecc.
- nota la parola supposto . Questa è una raccomandazione: "Questo è il modo in cui intendiamo essere il preferito". Che può (o non può) essere chiamato da dove il dominio della documentazione di riferimento è diretto.
Alcune società, ad es. Microsoft, segrega la panoramica di più alto livello in un tipo separato di documentazione. In molti posti in MSDN, vedresti una sezione su X divisa in: "Informazioni su X", "Uso di X" e "Riferimento X".
Come puoi vedere, la guida e il riferimento di un utente si completano a vicenda, coprono argomenti diversi e spiegano le cose da diversi punti di vista. Sebbene la guida sia più utile per l'utente nel breve periodo mentre la documentazione di riferimento a lungo termine.
-
Poiché il riferimento è completo, è "superiore" alla guida di un utente in quanto qualsiasi informazione che sarebbe presente in quest'ultimo può essere dedotta da esso, anche se a costo di una curva di apprendimento più ripida.
-
La guida per l'utente di OTOH è molto, molto più piccola e meno gravosa da mantenere, specialmente se l'interfaccia cambia rapidamente. Il rovescio della medaglia è che i tuoi utenti non sono mai sicuri se quello che stanno cercando di fare, a parte i pochi esempi che hai dato funzionino o no, quale sintassi è permessa dove ecc. - con conseguente enorme spreco del loro tempo.
man pages è un classico esempio di documentazione di riferimento. Alcuni autori della pagina man (ad esempio rsync ) hanno provato ad aggiungere sezioni guida dell'utente e, facendo ciò, hanno reso più difficile trovare le sezioni di riferimento necessarie.