Una guida alla scrittura di una buona documentazione

Questo post è stato contribuito dall'autore ospite Jeff Matson. Jeff è il capo della documentazione per GravityForms. È il creatore del plug-in WordPress Heartbeat Control ed è un fan degli anni '90.

Spesso, la documentazione è la parte più sottovalutata del processo di sviluppo. Quando guardiamo alle rockstar nella comunità di WordPress, di solito guardiamo a sviluppatori, designer e marketer. Poco si sa degli autori di documenti là fuori che hanno versato sangue, sudore e lacrime per assicurarsi che tutto funzioni senza intoppi.

Questo post parla di coloro che giorno dopo giorno fissano infinite righe di codice per decifrare ciò che lo sviluppatore stava pensando e il vero significato dietro il codice che esiste.

Una buona documentazione è più delle parole

I buoni scrittori di documentazione forniscono più di un manuale di istruzioni, forniscono un'esperienza. Ho conosciuto ottimi documentari, allenato principianti e la più grande differenza tra loro è capire il cervello di chi lo legge. Proprio come un romanzo, la documentazione ha un flusso che mantiene il lettore interessato e ingerisce più informazioni di quante se ne rendano conto.

La documentazione di qualità si rivolge agli utenti che hanno maggiori probabilità di leggerla. Fornisce anche un punto di riferimento per coloro che hanno meno probabilità di leggerlo. Ad esempio, se si documenta un particolare hook, in genere si presume che lo leggerà uno sviluppatore, ma che dire di coloro che hanno poca esperienza di sviluppo?

Un buon redattore di documentazione fornirà un punto di riferimento per coloro che hanno bisogno di più di una spinta nella giusta direzione, senza la necessità di contattare l'assistenza per spiegarglielo.

La documentazione ha un impatto maggiore di quanto pensi

La maggior parte semplicemente ignora la documentazione, spingendola nell'abisso infinito finché non ce la fanno più. Sono colpevole della stessa cosa in alcuni casi. Quello che queste persone non si rendono conto è che ogni momento in cui il loro plugin o tema non viene documentato, l'esperienza dell'utente ne risente.

Diamo un'occhiata al tuo ticket di supporto più comune. Se documentassi meglio il problema, quei biglietti andrebbero via del tutto? Probabilmente no. Riceveresti meno ticket relativi al problema e aumenteresti la produttività tua o del tuo agente di supporto? Lo garantisco. Penso che tutti potremmo usare meno ticket di supporto.

Come accennato in precedenza, la documentazione ha un impatto drammatico sull'esperienza dell'utente. Se l'utente è in grado di individuare le informazioni in modo semplice ed efficiente, ha risparmiato il proprio tempo e il tuo. L'aspettativa di vita media mondiale è di 66,57 anni e i tuoi utenti preferirebbero fare qualcos'altro con le loro vite piuttosto che giocherellare con documentazione scritta male.

Se un cliente vede che hai dedicato un bel po' di tempo e fatica alla tua documentazione, ti apprezzerà meglio, consapevolmente o meno. Una buona documentazione mostra che tieni a loro dopo la vendita iniziale.

Sei mai stato lasciato all'asciutto dopo aver speso soldi guadagnati duramente e presto ti sei pentito dell'acquisto? Penso che tutti abbiamo. Con un'adeguata documentazione, puoi evitare di trasmettere quella sensazione ai tuoi clienti.

Come puoi scrivere una documentazione migliore?

Il primo passo è smettere di evitarlo. Una volta che sei bravo, scrivere documentazione è un'esperienza più piacevole di quanto pensi. In effetti, diventerà una seconda natura. Proprio come qualsiasi altra cosa al mondo, la pratica rende perfetti.

Uno dei primi passi che vuoi fare quando decidi di portare la tua documentazione al livello successivo è determinare i tuoi punti deboli. Per cosa sei stato contattato? Se inizi a scrivere ciecamente di cose, potresti scoprire che ciò di cui stai scrivendo non sta avendo l'impatto che vorresti.

Una delle migliori tecniche che ho scoperto è tenere traccia del numero di biglietti che sono documentati rispetto a quelli che non lo sono e suddividere quelli che non sono in categorie. In questo modo, puoi indirizzare meglio i tuoi punti dolenti e rivedere le parti che potrebbero non essere utili come dovrebbero.

Dopo aver determinato quale documentazione dovresti scrivere, dovresti determinare il tuo pubblico di destinazione e suddividerlo in sviluppatori, utenti e utenti esperti. Questo ti aiuta a soddisfare quel particolare pubblico. Vedremo come indirizzare quegli utenti un po' più avanti.

Successivamente, vuoi scomporre il documento. Per gli sviluppatori, ti consigliamo di scomporlo in informazioni grezze (argomenti accettati, valori restituiti, ecc.), Esempi specifici e casi d'uso. Per gli utenti, la migliore linea d'azione è una procedura dettagliata. Ogni passo che dovranno compiere, per quanto banale possa sembrare, è fondamentale.

Spiegalo a loro in ogni fase del processo. La documentazione per utenti esperti è molto simile a uno scenario utente, ma più strutturata e scansionabile. Sii chiaro, ma consenti loro di saltare facilmente dove devono andare senza prima leggere il passaggio precedente.

L'arte di scrivere una migliore documentazione

Quando si tratta dell'arte di scrivere la documentazione, scrivi in ​​un modo che si rivolga meglio al tuo pubblico, ma usa anche un linguaggio semplice che sai che capirà. Uno dei migliori motivi per questo è dovuto alle traduzioni. Sebbene Google Translate faccia un ottimo lavoro, è molto più facile tradurre il semplice vocabolario di un alunno di quinta elementare rispetto a quello contenuto in una tesi post-laurea.

All'interno dei tuoi contenuti, non aver paura di collegarti a contenuti pertinenti. Ciò ti consentirà di evitare di ripeterti su più documenti, oltre a consentire al lettore di tornare indietro se ha bisogno di maggiori informazioni su un argomento particolare. Dopotutto, i tuoi obiettivi principali sono rendere felice l'utente e risparmiare tempo.

Il processo di documentazione non si interrompe dopo aver premuto il pulsante di pubblicazione . Torna indietro e rivedi ogni documento secondo necessità. Quasi immediatamente dopo la pubblicazione del documento, torna indietro e controlla se i ticket di supporto che hai monitorato sono diminuiti e il traffico verso quel particolare articolo è aumentato. Di solito, se stai ricevendo più traffico su un articolo, sta aiutando. Se stai ricevendo più traffico ma lo stesso numero di ticket di supporto, potresti voler esaminare quell'articolo per vedere perché.

Quello che abbiamo imparato

Innanzitutto, spero che dopo essere arrivato così lontano, tu abbia un migliore apprezzamento per quelli in trincea che scrivono la documentazione che la maggior parte di noi dà per scontata. È davvero una forma d'arte che molti di noi che scrivono documentazione per vivere apprezzano davvero e dedicano molte, molte ore.

Spero anche che tu esca da questo articolo pensando di più alla tua documentazione esistente e a come può essere migliorata. Una corretta documentazione può essere estremamente gratificante e, una volta messa in pratica, può essere davvero divertente da scrivere.

Documenta in anticipo, documenta spesso. Un ottimo prodotto è più di un ottimo codice, è anche ben documentato.