18 Software Documentation Tools that Do The Hard Work For You

🟢 Materiale bonus: Git Workflow Checklist per semplificare & ottimizzare la gestione delle versioni

Senza documentazione, il software è solo una scatola nera. E le scatole nere non sono neanche lontanamente utili come potrebbero essere perché il loro funzionamento interno è nascosto a coloro che ne hanno bisogno all’aperto.

La documentazione del software trasforma il tuo software in una scatola di vetro spiegando agli utenti e agli sviluppatori come funziona o viene usato.

Probabilmente avete già visto la documentazione, ma se avete bisogno di un ripasso, ecco un esempio dalle API di Slack:

Come potete vedere, Slack spiega ogni cosa delle sue API in dettagli strazianti. Tutte le pagine correlate sono collegate, c’è una barra laterale con argomenti di facile accesso, e screenshot di ciò che l’utente può aspettarsi di vedere.

Per spiegare questo in modo più dettagliato, copriremo i seguenti argomenti in questo post di Process Street:

• Cos’è la documentazione del software?
• Opzioni di hosting della documentazione del software
• Strumenti di scrittura per la documentazione del software
• Parole finali sulla documentazione del software

Partiamo.

Cos’è la documentazione del software?

“La documentazione nell’ingegneria del software è il termine ombrello che comprende tutti i documenti e i materiali scritti che hanno a che fare con lo sviluppo e l’uso di un prodotto software” – Prototype.io, Software Documentation Types and Best Practices

Tutti i pezzi di software dovrebbero avere una qualche forma di documentazione che spiega, in dettaglio, cos’è il prodotto, come funziona e perché funziona in quel modo.

“Se non è documentato, non esiste” – Sitepoint, A Guide to Writing Your First Software Documentation

Come sviluppatore, il tuo obiettivo principale è scrivere il miglior codice possibile. Vuoi che il tuo codice sia il migliore della classe, facile da leggere, facile da usare, e vuoi che accadano grandi cose come risultato. Giusto?

Ma senza documentare quello che hai fatto e perché l’hai fatto:

• Nessun altro può usare il tuo codice tranne te

Senza documentazione, nessuno capirà cosa hai fatto e perché l’hai fatto. Sarà incredibilmente difficile, quasi impossibile, per qualcun altro prendere il vostro codice e lavorarci sopra. Potrebbero anche scartarlo e ricominciare da capo, dato che, in alcuni casi, sarebbe più veloce che cercare di capire cosa avete fatto e perché.

• Non puoi aggiornarlo o migliorarlo

Ti ricordi cosa hai mangiato a cena sabato, tre mesi fa? A meno che tu non sia una completa creatura abitudinaria, è probabile che tu non ci riesca. Quindi è giusto dire che probabilmente non ricorderete il codice che avete scritto, due, tre, quattro mesi dopo averlo fatto. Se non riuscite a ricordare le ragioni dietro le vostre decisioni di codifica, allora farete fatica ad essere in grado di aggiornarlo o migliorarlo.

Nonostante questo, la documentazione del software è spesso un compito che viene affrettato, fatto male, depriorizzato, o completamente dimenticato.

Prima di iniziare a parlare di quali strumenti si possono usare per scrivere la documentazione del software, dobbiamo pensare a un modo per assicurarci che il compito venga svolto in primo luogo.

Ecco dove Process Street può aiutare.

Process Street è un software di gestione dei processi aziendali (BPM) che può essere usato per creare, gestire e seguire i processi.

Più avanti su cosa è Process Street, per ora, lasciate che vi mostri come potete usarlo come strumento per aiutarvi a inserire la documentazione del software in ogni progetto di sviluppo del software su cui lavorate.

Qui sotto c’è un esempio di un modello pre-fatto di Software Deployment Process. Questo modello è stato creato per aiutare gli ingegneri del software e i programmatori a distribuire il loro software nel miglior modo possibile.

Clicca qui per accedere al Software Deployment Process!

Per ottenere questo modello, effettua il login e aggiungilo alla tua dashboard, oppure registrati per una prova gratuita.

Questo modello è un perfetto esempio di un processo che puoi seguire ogni volta che vuoi distribuire un pezzo di codice nuovo o aggiornato.

Ha dei passi chiari che ti guideranno attraverso l’intero processo di distribuzione, dall’impostazione di un ambiente di staging alla messa in opera delle modifiche. Questi passi faranno in modo che nulla venga tralasciato e che l’intero processo vada liscio ogni volta.

Abbiamo progettato questo modello da usare come guida per aiutarvi a creare un processo di distribuzione che funzioni per voi. Ogni azienda è diversa, ogni progetto software è diverso e ogni processo di distribuzione è diverso.

Puoi modificare questo processo e aggiungere i compiti che sono rilevanti per te, la tua azienda e il tuo progetto.

Che mi riporta alla documentazione del software; potresti aggiungere “documentazione del software” come compito. In questo modo, a chiunque lavori attraverso il processo di distribuzione del software verrà ricordato e incoraggiato a completarlo, come parte del processo.

Ho alcuni altri modelli di processo preconfezionati che potrebbero esservi utili, che includerò alla fine di questo post.

Prima di arrivare a questo, guardiamo dove potete memorizzare la vostra documentazione software.

Opzioni di hosting della documentazione software

Non va bene avere solo un mucchio di file di testo che vivono sul vostro computer. Devono essere accessibili agli sviluppatori e agli utenti, cosa che molto probabilmente farai ospitando i documenti su internet, dato che non sono gli anni ’80.

Process Street (per uso interno)

Per formare nuovi sviluppatori e mantenere la tua documentazione nello stesso posto, Process Street è una scelta solida per la documentazione del software.

Prima di tutto, potresti creare un processo per scrivere la tua documentazione, per essere sicuro di catturare tutti i dettagli giusti e renderla il più utile possibile.

Utilizzando le seguenti funzioni facili da usare, si può poi scrivere e archiviare la documentazione in un unico posto:

• Widget immagine
• Widget testo
• Widget video
• Widget file
• Subtasks
• Widget e-mail
• Widget embed

Memorizzare la documentazione in Process Street significa che è accessibile a tutti in azienda. Puoi condividerla con gli altri, inviarla per l’approvazione, impostare promemoria per rivederla e aggiornarla facilmente.

Guarda qui:

Se può essere documentato, può essere documentato in Process Street.

Iscriviti per una prova gratuita qui e provalo.

Leggi i documenti

È notevole che Read The Docs sia gratuito quando si vede tutto quello che può fare. Simile a GitHub, puoi creare tutto il materiale open-source che vuoi e che viene indicizzato apertamente sul sito, ma ti costerà se vuoi rendere i documenti privati e interni alla tua azienda. Per i nostri scopi, è probabile che vi vada bene avere i documenti prontamente disponibili per gli utenti sul web.

La ragione per cui Read The Docs è così buono è che si può importare senza sforzo la documentazione da qualsiasi sistema di controllo della versione incluso Git, Mercurial, Subversion e Bazaar. Supporta anche i webhooks in modo che i documenti vengano compilati automaticamente ogni volta che si commette del codice.

Guarda la loro guida introduttiva per avere un’idea di come funziona e di come i tuoi documenti si comportano quando sono ospitati lì.

GitHub (& GitHub Pages)

Se stai usando GitHub per gestire il controllo di versione del tuo software, hai, come minimo, un file README.MD nel repository. Per usare GitHub per documentare il tuo software, come milioni di altri hanno fatto in passato, basta riempire quel README con markdown.

Un grande esempio è il repository t di sferik, screenshotted here:

Se vuoi più di un semplice foglio di testo formattato, puoi approfittare dello strumento Pages di GitHub (ottieni una pagina web gratuita + hosting con ogni account GitHub, e puoi anche indirizzarci un dominio personalizzato). Pages ha anche temi di default molto belli che rendono la tua documentazione professionale.

Questa è la documentazione di atom.io per Electron ospitata su GitHub. È una scelta intelligente perché funziona automaticamente con il controllo di versione di GitHub, proprio come il resto del vostro software. Vedi il repository del sito qui.

Dropbox Paper (per uso interno)

Per la documentazione interna del software, Dropbox Paper è una scelta eccellente. Come il suo predecessore Hackpad, è possibile utilizzarlo per creare un wiki privato per i dipendenti. È possibile collegare i documenti insieme, inserire blocchi di codice, immagini e salti di pagina, proprio come si pretende da qualsiasi strumento di documentazione.

Come si può vedere dai commenti sulla destra, è anche possibile utilizzarlo per passare attraverso processi di approvazione e collaborare alla creazione della documentazione. Nel complesso, è un ottimo strumento per lo sviluppo interno e la creazione di documentazione, forse con la prospettiva di pubblicarla in seguito, o semplicemente tenerla per uso interno.

Atlassian REST API Browser (per l’uso delle API)

Atlassian’s REST API Browser (RAB) è incluso in JIRA Server, Confluence Server e Stash istanze per impostazione predefinita. È costruito per scoprire le API disponibili per l’uso negli ambienti JIRA/Confluence, e anche un posto per ospitare la tua documentazione. Se, naturalmente, la vostra API rientra nel conto.

Documentate la vostra API usando questo strumento per dare più visibilità alla vostra API compatibile con JIRA/Confluence. Controlla qui la documentazione di Atlassian su come farlo.

Tettra (per uso interno)

Tettra è una specie di software di base di conoscenza dove puoi documentare il tuo sviluppo, o qualsiasi cosa.

Utilizziamo Tettra internamente a Process Street per un sacco di casi d’uso. Giorno per giorno, uso Tettra per avere un unico posto dove tutti i miei processi sono documentati in modo da non dimenticare mai come uno è collegato all’altro o come le varie automazioni che abbiamo costruito sono state impostate.

Tettra è ottimo se stai cercando di creare una sorta di biblioteca. Questo significa che è brillante per la documentazione del software o anche solo come wiki interno per la vostra azienda.

Dato che Tettra è specificamente progettato per la gestione della conoscenza, è dotato di una serie di altre caratteristiche di supporto. Per esempio, può dare suggerimenti su quali contenuti extra o sezioni si potrebbero aggiungere per dare un quadro più completo della vostra organizzazione e di come le cose stanno insieme.

Si può vedere un piccolo video qui su come un team di sviluppo potrebbe usare Tettra: How Product & Engineering Teams Use Tettra.

Oppure, puoi andare qui per leggere come usiamo Tettra insieme a Process Street: Automatizzare i flussi di lavoro e le liste di controllo: Process Street Case Study.

Controlla!

Apiary (for API use)

Oltre ad essere un posto dove vivono le api, Apiary è un host dedicato alla documentazione API. Scrivete in markdown, aggiungete finte chiamate API e Apiary raccoglie il tutto in qualcosa come vedete qui sotto:

Chiunque può testare l’API senza dover entrare nell’app o programmare effettivamente una chiamata, il che lo rende un modo super accessibile per condividere la vostra API, documentarla a fondo e vantarsi di ciò che può fare.

Abbiamo discusso dove conservare la documentazione del vostro software, ora è il momento di vedere come scriverla.

Strumenti di scrittura per la documentazione del software

La documentazione del software è spesso scritta in markdown per consentire collegamenti ipertestuali e formattazione, pur mantenendo il testo semplice in modo che possa vivere accanto ai file di codice nel controllo di versione. Questo significa che molte delle mie scelte per gli strumenti di scrittura sono semplici editor markdown che rendono l’esperienza di scrittura piacevole. Inoltre, ci sono anche un paio di soluzioni non-mparkdown molto efficaci.

MarkdownPad (Windows)

Con una versione gratuita e una premium – entrambe con una tonnellata di grandi caratteristiche – MarkdownPad è il più popolare editor markdown per Windows. E’ ottimizzato per post di blog, siti web, articoli, README e, naturalmente, documentazione software.

Puoi avere MarkdownPad gratuitamente, o ottenere la versione premium per $14.95.

iA Writer (Mac)

iA Writer è un editor markdown semplice e bello con una funzione di libreria che ti permette di fare facilmente riferimento ad altri documenti nella barra laterale. Mancano i collegamenti interni tra i documenti come ci si aspetta che ci siano nei documenti software, ma si può sempre fare un passaggio su quelli quando è nella sua forma finale (cioè, se sta per finire su internet in un sito).

Se si scrive l’intera documentazione in una pagina spezzata, si possono usare ancore di salto pagina per aiutare gli utenti a navigare.

iA Writer costa 9,99 dollari dal Mac App Store.

Profs Knowledge Base

Profs Knowledge Base è un fantastico piccolo strumento per tutte le fasi della creazione dei documenti; dalla scrittura e la modifica, alla personalizzazione, l’impostazione dei flussi di lavoro e la pubblicazione. È possibile aggiungere multimedia, importare contenuti esistenti da documenti Word, PDF o PPT, salvare più versioni del documento e ripristinarle quando necessario.

Ma la vera bellezza di questo strumento sta nella sua usabilità. Chiunque e tutti possono usarlo per costruire documentazione software. Sia che tu abbia documentato il software per anni o che tu abbia iniziato solo di recente, è uno strumento incredibilmente semplice e facile da usare.

Profs è gratuito da usare, o puoi passare al pacchetto premium che costa 112 dollari al mese.

SimpleMDE (browser)

Mentre tecnicamente puoi scrivere markdown in qualsiasi editor di testo perché è un modo per formattare il testo semplice, non strettamente uno ‘strumento’, non ti sorprenderà che sia possibile anche nel tuo browser! SimpleMDE è sia un editor markdown funzionale costruito su JavaScript che un progetto open-source da cui imparare e adattare per il proprio uso, se necessario.

SimpleMDE è 100% gratuito! Prendete il sorgente su GitHub qui.

Editori reStructuredText

Markdown è uno dei due linguaggi più comunemente usati per scrivere documentazione software, ma ce n’è un altro che non abbiamo visto finora, ed è reStructuredText. È molto simile a markdown, ma vale la pena impararlo per scopi di documentazione software.

Docutils, il creatore di reStructuredText, ha messo insieme una lista di editor reStructuredText qui, che include:

Il punto di reStructuredText è che è facile convertire tra diversi formati, specialmente da testo semplice a un sito web statico. Vedi maggiori informazioni qui.

Tools per generare automaticamente la documentazione dal codice sorgente

Non c’è niente come il tocco umano quando si tratta di documentazione (è chiaro nei documenti di Slack e Giphy, per nominarne un paio). Tuttavia, come punto di partenza (specialmente per enormi librerie di sorgenti), è meglio generare la documentazione scheletrica automaticamente. Questo funziona analizzando le funzioni e i commenti del sorgente, e ci sono alcune opzioni diverse a seconda della lingua:

Prima di andare avanti e fare affidamento solo sulla generazione automatica, ti consiglio di leggere questo thread di StackExchange che valuta i pro e i contro.

Parole finali sulla documentazione del software

Ci sono un sacco di soluzioni fantasiose, soluzioni rapide e strumenti che sono (onestamente) quasi identici. Ciò che conta alla fine è che

Quello che conta di più, alla fine, è che:

a) scrivi la documentazione del software per ogni pezzo di software che costruisci
b) la scrivi in modo completo e la ospiti da qualche parte dove l’utente può accedere

Prima ho detto che ho qualche altro modello di processo di sviluppo che potresti essere interessato a controllare?

Ebbene, eccoli qui…

Modelli di processo di sviluppo di Process Street

Prima di darti questi modelli, lascia che ti spieghi meglio cos’è Process Street.

Quindi sappiamo che Process Street è una lista di controllo superpotenziata. È un software che vi aiuterà a creare e gestire i processi.

Ma aspetta, c’è molto di più in Process Street!

Guarda questo video introduttivo per scoprire cosa intendo:

Così vedi, non solo puoi creare un modello di processo di sviluppo ed eseguire singole checklist da questo ogni volta che hai bisogno di completare il processo di sviluppo, ma puoi personalizzarlo usando queste caratteristiche extra

• Fermare i compiti
• Date di scadenza dinamiche
• Permessi per i compiti
• Logica condizionale
• Tempi di approvazione
• Vedova incorporata
• Assegnazione dei ruoli

Assegnare compiti, ottenere l’approvazione, imporre un ordine in cui i compiti sono completati, e si può collegare il processo a migliaia di applicazioni tramite Zapier, webhooks, o integrazione API.

Guarda questo webinar sulle nostre nuove funzionalità e scopri come puoi sfruttarle al meglio:

Con tutto questo in mente, dai un’occhiata ai seguenti modelli pre-fatti:

Network Security Audit Checklist

Questo modello può essere utilizzato da un risk manager o da un professionista IT equivalente per valutare una rete per le vulnerabilità di sicurezza.

Clicca qui per accedere alla Checklist Network Security Audit!

Lista di controllo mensile per la manutenzione del sito web

Utilizza questa lista di controllo mensile per la manutenzione del sito per ottimizzare la velocità di caricamento del tuo sito, scansionare le vulnerabilità e rivedere la visibilità di ricerca.

Clicca qui per accedere alla lista di controllo mensile per la manutenzione del sito web!

Software Testing Tutorial

Questo processo può essere usato per gestire un intero progetto di sviluppo software dall’inizio alla fine, incluso il design, la gestione del cliente e anche i controlli post-lancio.

Clicca qui per accedere al Software Testing Tutorial!

Ed eccoti servito.

Sei ora libero di usare qualsiasi cosa ti renda la vita più facile. Spero che troviate il vostro nuovo strumento preferito in questa lista.