Sviluppatori Perché non si deve saltare la documentazione

Nel campo dello sviluppo di app per dispositivi mobili, app Web, app desktop o librerie JavaScript, la documentazione svolge un ruolo importante che potrebbe determinare il successo dello sviluppo del software. Ma se hai mai fatto documentazione, saresti d'accordo con me sul fatto che è praticamente la cosa meno gradita agli sviluppatori.

A differenza del codice di scrittura (che è ciò che gli sviluppatori hanno firmato per fare), la documentazione (che non abbiamo) deve e deve essere facilmente digerita da tutti. Tecnicamente, dobbiamo tradurre un linguaggio macchina (codice) in un linguaggio comprensibile per gli umani, che è più duro di quanto suoni.

Anche se può essere davvero oneroso, scrivere la documentazione è importante e offrirà vantaggi per i tuoi utenti, i tuoi colleghi e soprattutto te stesso.

Una buona documentazione aiuta gli utenti

La documentazione aiuta il lettore capire come funziona un codice, ovviamente. Ma molti sviluppatori commettono l'errore di presumere che gli utenti del software saranno abili. Quindi, la documentazione può essere materiale sottile, saltando molti degli elementi essenziali che avrebbe dovuto contenere fin dall'inizio. Se sei esperto nella lingua, puoi capire le cose di tua iniziativa; se non lo sei, allora sei perso.

La documentazione destinata agli utenti di solito consiste in un uso pratico o in “come”. La regola generale quando si crea la documentazione per gli utenti generici è quella dovrebbe essere chiaro. Usare parole umane è preferibile a termini tecnici o gergali. Anche gli esempi di uso reale saranno molto apprezzati.

Un buon design del layout aiuterebbe davvero gli utenti a scansionare ogni sezione della documentazione senza affaticare gli occhi. Alcuni buoni esempi (alias i miei preferiti) sono la documentazione per Bootstrap e WordPress ' “Primi passi con WordPress”.

Aiuta anche altri sviluppatori

Ogni sviluppatore avrà il proprio stile di codifica. Ma quando si tratta di lavorare in un team, dovremo spesso condividere i codici con gli altri compagni di squadra. Quindi è essenziale avere un consenso su uno standard per mantenere tutti sulla stessa pagina. Una documentazione scritta correttamente sarebbe il riferimento di cui la squadra ha bisogno

Ma a differenza della documentazione per l'utente finale, questa documentazione in genere descrive procedure tecniche come la convenzione di denominazione del codice, che mostra come devono essere costruite particolari pagine e come l'API funziona insieme agli esempi di codice. Spesso dovremmo anche scrivere la documentazione in linea con il codice (noto come Commenti) per descrivere cosa sta facendo il codice.

Inoltre, nel caso in cui tu abbia nuovi membri che si uniscono la tua squadra più tardi, questa documentazione potrebbe essere un modo efficace per allenarli, quindi non devi dare loro un run down 1-on-1 sul codice.

Stranamente aiuta anche il Coder

La cosa divertente della programmazione è che a volte anche gli stessi sviluppatori non comprendono il codice che hanno scritto. Questo è particolarmente vero nei casi in cui i codici sono stati lasciati intatti per mesi o addirittura anni.

Un improvviso bisogno di rivisitare i codici per una ragione o l'altra lascerebbe uno a chiedersi cosa stesse succedendo nella loro mente quando hanno scritto questi codici. Non essere sorpreso: sono stato in questa situazione prima. Questo è precisamente quando io desiderato Ho documentato correttamente il mio codice.

Documentando i tuoi codici, sarai in grado di arrivare alla fine dei tuoi codici in modo rapido e senza frustrazione, risparmiandoti molto del tuo tempo che può essere speso per ottenere i cambiamenti in.

Cosa rende una buona documentazione?

Ci sono diversi fattori per costruire una buona documentazione.

1. Non assumere mai

Non dare per scontato che i tuoi utenti sappiano cosa tu sapere oltre a cosa essi voglio sapere. È sempre meglio iniziare dall'inizio indipendentemente dal livello di competenza degli utenti.

Ad esempio, se hai creato un plugin jQuery, potresti trarre ispirazione dalla documentazione di SlickJS. Mostra come strutturare l'HTML, dove mettere il CSS e il JavaScript, come inizializzare il plugin jQuery al suo livello più elementare, e mostra anche il markup finale completo dopo aver aggiunto tutte queste cose, che è qualcosa di ovvio.

La linea di fondo è che la documentazione è scritta con il processo di pensiero di un utente, non di uno sviluppatore. Avvicinarsi alla tua documentazione in questo modo ti darà una prospettiva migliore nell'organizzazione del tuo pezzo.

2. Segui lo standard

Nell'aggiunta di documentazione che va in linea con il codice, utilizzare lo standard previsto per la lingua. È sempre una buona idea descrivere ciascuna funzione, le variabili e il valore restituito dalla funzione. Ecco un esempio di buona documentazione inline per PHP.

 / ** * Aggiunge classi personalizzate alla matrice di classi del corpo. * * @param array $ classes Classi per l'elemento body. * @return array * / function body_classes ($ classes) // Aggiunge una classe di blog di gruppo ai blog con più di 1 autore pubblicato. if (is_multi_author ()) $ classes [] = 'blog di gruppo';  return $ classes;  add_filter ('body_class', 'body_classes'); 

I seguenti sono alcuni riferimenti per la formattazione della documentazione in linea con le migliori pratiche in PHP, JavaScript e CSS:

• PHP: PHP Documentation Standard per WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Se stai usando SublimeText suggerirei di installare DocBlockr che abilmente precompilerà il tuo codice con la documentazione integrata.

3. Elementi grafici

Usa elementi grafici, parlano meglio del testo. Questi media sono utili, soprattutto se si crea software con interfaccia grafica. È possibile aggiungere elementi di puntamento come frecce, cerchi o tutto ciò che può aiutare gli utenti a capire dove andare a compiere i passi, senza congetture.

Di seguito è riportato un esempio dall'app Tower in cui è possibile trarre ispirazione. Esse spiegano in modo efficiente come funziona il controllo della versione in un modo piacevole che lo rende più comprensibile rispetto all'utilizzo di righe di comando in chiaro.

4. Sezionamento

Si può prendere in considerazione il confezionamento di alcune cose nella documentazione all'interno di elenchi puntati e tabelle in quanto ciò rende più facile la scansione e la lettura degli utenti per i contenuti più lunghi.

Aggiungi una tabella di contenuti e dividi la documentazione in sezioni facilmente digeribili, mantenendo tuttavia ogni sezione pertinente con ciò che viene dopo. Tenerlo breve e diretto. Di seguito è riportato un esempio di documentazione ben organizzata in Facebook. Il sommario ci porta dove vogliamo saltare in un clic.

5. Revisione e aggiornamento

Infine, rivedere la documentazione per gli errori e rivedere quando necessario o e ogni qualvolta vi siano modifiche significative al prodotto, al software o alla libreria. La tua documentazione non sarebbe utile a nessuno se non fosse regolarmente aggiornata insieme al tuo prodotto.