Cos'è la documentazione software? Tipi e best practice per iniziare

Se desideri che sviluppatori e utenti finali ottengano il massimo valore possibile dal tuo software, devi creare una documentazione software di alta qualità.

Ma cos'è veramente la documentazione del software e come puoi crearla per il tuo progetto?

In questo post, analizzeremo tutto ciò che è necessario sapere sulla documentazione del software, incluso quanto segue:

• Cos'è la documentazione del software?
• I diversi tipi di documentazione software (con esempi)
• Come pubblicare la documentazione del tuo software (i migliori strumenti)
• Alcune best practice per la creazione di documentazione software di qualità

Scaviamo!

Cos'è la documentazione software?

La documentazione del software è un contenuto che aiuta gli utenti finali, gli sviluppatori e/oi dipendenti a comprendere il software e a utilizzarlo per raggiungere efficacemente i propri obiettivi.

In genere, pubblicherai la documentazione del software sul tuo sito web. Le persone possono quindi accedervi per saperne di più sul tuo software e su come funziona.

All'interno di questa ampia definizione di documentazione software, esistono diversi tipi di documentazione software. Parliamone dopo.

I diversi tipi di documentazione software

È possibile suddividere approssimativamente i diversi tipi di documentazione software in poche grandi categorie.

La prima considerazione è a quale tipo di persona è destinata la documentazione:

• Documentazione per l'utente : questa è la documentazione che hai creato per l'utente finale del prodotto. Li aiuta a capire come utilizzare il software dal punto di vista di un utente normale, che può avere o meno conoscenze tecniche speciali.
• Documentazione per sviluppatori : si tratta di documentazione software più tecnica che hai creato per gli sviluppatori, come la documentazione API.

La seconda considerazione è se la documentazione è destinata a un pubblico esterno o interno:

• Documentazione software esterna : si tratta di documentazione pubblica che hai creato per aiutare i tuoi utenti.
• Documentazione software interna : si tratta di documentazione privata che hai creato per i tuoi dipendenti per aiutarli a lavorare in modo più efficace e comprendere i dettagli chiave.

Ad esempio, potresti avere una serie di documentazione per sviluppatori per i tuoi team interni per aiutarti a lavorare sul software e un'altra serie di documentazione per sviluppatori pubblica per sviluppatori esterni.

Analizziamo questi tipi di documentazione software in modo un po' più dettagliato...

Esempi di documentazione software per la documentazione per sviluppatori

• Documentazione API : mostra agli sviluppatori come interagire con l'API del tuo software.
• Leggimi : presenta il tuo software e spiega cosa fa, in genere la prima cosa che le persone leggono.
• Note sulla versione : documenta le nuove versioni del tuo software, incluse eventuali modifiche importanti.
• Documentazione dell'architettura : mostra la struttura del tuo software, includendo potenzialmente diagrammi.
• Documentazione del modello di dati : documenta le diverse strutture di dati nel tuo software, comprese le relazioni tra le diverse strutture di dati.
• Documentazione di processo : documenta i processi chiave come segnalazioni di bug, roadmap, garanzia della qualità, protocolli di test e così via.

Per un vero esempio di documentazione software di documenti incentrati sugli sviluppatori, puoi consultare la documentazione "Sviluppatori" di Gravity Forms che copre vari argomenti come:

• Hook PHP (per WordPress)
• Oggetti dati
• API PHP
• Banca dati
• API REST

Ad esempio, ecco come appare la documentazione dell'API REST:

Esempi di documentazione software per la documentazione utente

• Guida introduttiva : mostra agli utenti come iniziare rapidamente a utilizzare il tuo software.
• Tutorial per casi d'uso specifici : tutorial più specifici per l'esecuzione di attività specifiche.
• Glossari terminologici/manuali di riferimento : aiutano gli utenti a comprendere termini e dettagli chiave.
• Domande frequenti : rispondi alle domande più frequenti.

Per un vero esempio di come potrebbe apparire una documentazione software più incentrata sull'utente, puoi passare allo stesso esempio di Gravity Forms dall'alto.

Se guardi gli articoli più incentrati sull'utente di Gravity Forms, vedrai molti tutorial passo-passo su come eseguire attività utilizzando l'interfaccia del software, insieme a glossari e spiegazioni delle funzionalità chiave.

Rispetto alla documentazione del software per sviluppatori, vedrai più schermate e spiegazioni in un linguaggio semplice e molti meno blocchi di codice.

Come pubblicare la documentazione del software: tre migliori strumenti di documentazione del software

Per pubblicare la documentazione del tuo software sul tuo sito web, avrai bisogno di uno strumento di documentazione del software dedicato o di un qualche tipo di sistema di gestione della conoscenza.

In questa sezione tratteremo rapidamente alcuni dei migliori strumenti di documentazione software. Quindi, nella sezione successiva, esamineremo alcune best practice per la creazione di documentazione di qualità.

Se vuoi dare uno sguardo più approfondito qui, potresti voler leggere le nostre guide complete sui migliori strumenti di documentazione e il miglior software di documentazione tecnica.

Base di conoscenza eroica

Heroic Knowledge Base è un plug-in di documentazione e knowledge base per il popolare software WordPress open source.

Con Heroic Knowledge Base, puoi ospitare autonomamente la tua documentazione e mantenere il pieno controllo, pur continuando ad accedere a tutte le funzionalità necessarie per creare una documentazione software efficace.

Ecco alcune delle funzionalità principali che ottieni con Heroic Knowledge Base:

• Editor di contenuti flessibile , inclusi blocchi integrati per callout e altri importanti dettagli di stile.
• Sommario automatico in modo che gli utenti possano vedere rapidamente quale contenuto è trattato in un articolo di documentazione e passare a sezioni specifiche.
• Controllo delle revisioni e cronologia delle versioni tramite il sistema di revisione nativo di WordPress.
• Funzionalità di scoperta dei contenuti , inclusa la ricerca Ajax in tempo reale con suggerimenti in tempo reale, categorie e altro ancora.
• Sistema di feedback degli utenti che consente alle persone di valutare gli articoli come utili o non utili e condividere feedback.
• Analisi di ricerca in modo da poter vedere cosa cercano gli utenti, nonché eventuali termini di ricerca che restituiscono zero risultati.
• Widget di risposte istantanee per consentire agli utenti di cercare e accedere alla documentazione del software da qualsiasi punto del tuo sito.

Poiché Heroic Knowledge Base e WordPress sono entrambi self-hosted e open-source, sei anche libero di modificare la tua configurazione secondo necessità.

Puoi renderlo pubblico o limitare l'accesso alla tua documentazione con varie tattiche come password, account utente, indirizzi IP, una intranet e altro.

Heroic Knowledge Base parte da soli $ 149 all'anno.

Leggi i documenti

Read the Docs è uno strumento di documentazione incentrato sull'aiutarti a creare documentazione per sviluppatori.

Se ti concentri specificamente sulla creazione di documentazione tecnica per sviluppatori, può essere un'altra buona opzione da considerare.

Puoi gestire i tuoi contenuti e la cronologia delle revisioni utilizzando Git e quindi distribuire i tuoi documenti su un'interfaccia front-end.

Ecco alcune delle altre caratteristiche degne di nota in Read the Docs:

• Analisi integrate per vedere cosa leggono e cercano i tuoi utenti.
• Supporta più build simultanee , il che può essere utile se offri più versioni del tuo software, ad esempio un set di documentazione per la versione 1.0 e un altro per la versione 2.0.
• Esporta la documentazione in diversi formati tra cui PDF, HTML ed epub.
• Suggerimenti di ricerca in tempo reale per aiutare gli utenti a trovare i documenti.

Read the Docs è gratuito se hai un progetto software open source.

Per i prodotti software commerciali, è disponibile un servizio a pagamento Read the Docs for Business che parte da $ 50 al mese.

GitBook

GitBook è un altro strumento di documentazione del software tecnico che ti consente di gestire la tua documentazione utilizzando Git, con supporto per i repository GitHub e GitLab.

Oppure, se non desideri utilizzare Git, GitBook ti consente anche di creare la tua documentazione utilizzando un editor di testo o di importarla da file markdown o .doc.

Ecco alcune altre caratteristiche degne di nota offerte da GitBook:

• Controllo della versione per tenere traccia delle revisioni e della cronologia delle versioni.
• Modifica dal vivo del team che è utile se è necessario che più autori collaborino agli articoli.
• Organizza gli articoli utilizzando "spazi" e "raccolte": ogni spazio può contenere più raccolte al suo interno.
• Opzione di esportazione PDF in modo che gli utenti possano facilmente esportare la documentazione come download PDF.

GitBook è gratuito per progetti no-profit o open-source.

Per i progetti software commerciali, GitBook parte da $ 8 per utente al mese, con un minimo di 5 utenti. Ciò significa che la tariffa mensile più economica è di $ 40 al mese.

Best practice per la creazione di documentazione software

Per finire, esaminiamo alcune best practice della documentazione software per aiutarti a creare una documentazione efficace.

Pensa agli obiettivi e alle esigenze degli utenti

Quando si scrive un articolo sulla documentazione del software, è importante iniziare rispondendo ad alcune domande di base:

• Chi è l'utente per cui stai scrivendo?
• Cosa sta cercando di ottenere l'utente?
• Che livello di conoscenza tecnica ha l'utente?

Conoscere le risposte a queste domande ti aiuterà a capire quali contenuti trattare e come strutturare l'articolo nel modo più ottimale.

Ad esempio, supponiamo che offri un software di pianificazione dei social media e stai scrivendo un articolo che aiuta i gestori dei social media a programmare il loro primo post sui social media.

Quando scrivi la documentazione del tuo software, dovresti concentrarti sul mostrare il modo più semplice per un normale utente finale di raggiungere questo obiettivo.

Se offri anche un'API per consentire agli sviluppatori di impostare le proprie integrazioni, probabilmente vorrai trattarla in un articolo diverso ( anche se potresti menzionare e collegarti a quel metodo ).

Includere la documentazione del software nel processo di sviluppo

Quando si crea la documentazione software, è facile cadere nella trappola di aspettare fino al completamento di un progetto per documentarlo.

Tuttavia, questo può portare rapidamente a un debito di documentazione perché potresti spedire nuove funzionalità o modifiche prima che siano state documentate.

Per evitare ciò, rendi la documentazione del software una parte consapevole del ciclo di sviluppo del software. Se una nuova funzionalità o prodotto non è stato ancora documentato, non è pronto per la spedizione anche se il codice stesso è finito.

Rendendo la documentazione un requisito fondamentale del processo di sviluppo del software, puoi assicurarti che tutto ciò che spedisci sia accompagnato dalla documentazione adeguata.

Usa formattazione e stile coerenti

Per aiutare le persone a lavorare in modo più efficace con la documentazione del software, è importante utilizzare una formattazione e uno stile coerenti in tutta la documentazione.

L'utilizzo della stessa formattazione consente ai lettori di apprendere come è strutturata la documentazione del software, il che renderà loro più facile l'accesso rapido alle informazioni di cui hanno bisogno.

Per aiutare a raggiungere questa coerenza, potresti voler creare una guida allo stile della documentazione del software dedicata.

Il tuo strumento di gestione della documentazione software potrebbe anche includere funzionalità che ti aiutano a ottenere uno stile coerente.

Ad esempio, il plug-in Heroic Knowledge Base include callout preimpostati per evidenziare informazioni chiave o avvisi. Usandoli, puoi garantire una formattazione coerente in tutta la tua documentazione.

Usa gli esperti per scrivere la documentazione tecnica

Per la documentazione software rivolta all'utente, potresti non aver bisogno di esperti in materia per scrivere il contenuto.

Tuttavia, per una documentazione software più tecnica, come la documentazione API incentrata sugli sviluppatori, probabilmente vorrai incaricare qualcuno con le conoscenze tecniche pertinenti per scrivere quei documenti.

Questo potrebbe essere uno scrittore tecnico dedicato con esperienza nel dominio, se la tua organizzazione ha le risorse da assumere per quella posizione. Oppure potrebbe essere uno dei tuoi sviluppatori.

L'importante è che chi scrive comprenda gli aspetti tecnici del tuo software a un livello sufficientemente profondo da spiegarlo ad altri utenti tecnici.

Semplifica la scoperta dei contenuti da parte delle persone (ricerca/filtro)

Man mano che la tua libreria di documentazione cresce, diventerà più difficile per gli utenti trovare gli articoli di documentazione che rispondono alle loro esigenze.

Per cercare di evitare questo problema, ti consigliamo di concentrarti sul miglioramento della rilevabilità della documentazione del software.

Una prima strategia consiste nel suddividere la documentazione per tipologia.

Ad esempio, in genere vorrai separare la documentazione per l'utente finale dalla documentazione del software per sviluppatori.

All'interno di ciò, puoi anche utilizzare le categorie per suddividere ulteriormente gli articoli. Puoi utilizzare categorie basate su funzionalità, casi d'uso, componenti aggiuntivi e così via, qualunque cosa abbia un senso logico per il tuo prodotto software.

In linea con lo stesso esempio di Gravity Forms dall'alto, puoi vedere che Gravity Forms divide la sua documentazione per l'utente finale per tipi di funzionalità.

Un'altra utile funzione di rilevabilità sono i suggerimenti di ricerca in tempo reale. Gli utenti possono iniziare a digitare una query pertinente nella casella di ricerca e visualizzare immediatamente gli articoli della documentazione che corrispondono a tale query.

Molti strumenti di documentazione includono funzionalità di ricerca in tempo reale integrate, tra cui Heroic Knowledge Base.

Mantieni aggiornata la documentazione del tuo software

Poiché il tuo software è in continua evoluzione, la tua documentazione software sarà sempre un work in progress.

Man mano che le cose cambiano nel tuo software, dovrai aggiornare prontamente la tua documentazione per riflettere tali modifiche.

Altrimenti, la tua documentazione non sarà solo "non utile", ma potrebbe effettivamente creare confusione nei tuoi utenti.

Per assicurarti che questi aggiornamenti avvengano, ti consigliamo di assegnare persone specifiche a possedere la documentazione e il processo di aggiornamento. In questo modo, non c'è ambiguità su chi è responsabile di mantenere tutto accurato.

Usa il feedback dei clienti per migliorare la tua documentazione

Oltre a far lavorare il tuo team alla revisione e all'aggiornamento della documentazione del software, dovrai anche tenere conto del feedback dei clienti.

I clienti possono fornire preziose informazioni su quanto sia utile (o potenzialmente non utile) un determinato articolo della documentazione software, insieme a dettagli su come migliorarlo.

Per automatizzare il processo di feedback dei clienti, ti consigliamo di cercare uno strumento di gestione della documentazione che includa funzionalità integrate per il feedback dei clienti.

Ad esempio, il plug-in Heroic Knowledge Base consente agli utenti di valutare un articolo come utile o non utile e, facoltativamente , fornire feedback in forma libera.

Puoi quindi visualizzare tutte queste informazioni dalla tua dashboard per individuare rapidamente gli articoli della documentazione che devi migliorare.

Inizia oggi stesso a documentare il tuo software

La documentazione del software aiuta te e i tuoi clienti a lavorare in modo più efficace e a ottenere più valore dal vostro software.

Esistono diversi tipi di documentazione software, quindi ti consigliamo di pensare a quali tipi soddisfano le esigenze del tuo progetto software.

Potresti avere una documentazione diversa per i team interni o esterni, nonché per diversi tipi di clienti, come sviluppatori e utenti finali.

Per creare una documentazione efficace, ti consigliamo di seguire le best practice di questo post.

Per pubblicare tale documentazione, puoi utilizzare uno strumento open source come Heroic Knowledge Base, che si basa sul potente software WordPress.

Otterrai la flessibilità e la proprietà di una piattaforma self-hosted, con tutte le caratteristiche e le funzionalità necessarie per pubblicare documentazione software di alta qualità.

Se vuoi saperne di più, clicca qui per accedere alla Base di conoscenza eroica.