I team di prodotto e sviluppo condividono lo stesso problema: la documentazione¶
I team di prodotto e i team di sviluppo software condividono entrambi una sfida comune: la documentazione.
La documentazione di prodotto si riferisce ai manuali e alle guide rivolte agli utenti che spiegano il flusso di lavoro e l'interfaccia utente di un prodotto. Come può un utente medio essere produttivo con questo prodotto? In questo senso, la documentazione di prodotto può essere utilizzata per prodotti software.
La documentazione software si riferisce alle tecnologie sottostanti, ai prerequisiti e agli attributi configurabili di un prodotto software. Come fanno gli amministratori IT a configurare, monitorare, ospitare e distribuire il prodotto software per gli utenti? Questo tipo di documentazione è importante, soprattutto quando entrano in gioco più versioni o branch.
In un certo senso, la documentazione di prodotto è come insegnare a qualcuno a guidare un'auto. Il volante gira l'auto, l'acceleratore la fa muovere, il pedale del freno la ferma. La documentazione software insegna a qualcuno come funziona l'auto. Il volante è collegato all'asse anteriore che gira le ruote anteriori per modificare la direzione di marcia; l'acceleratore aumenta il flusso d'aria al motore che attira più carburante, generando coppia e potenza.
Entrambi i tipi di documentazione sono importanti. Una educa gli utenti, l'altra educa amministratori e sviluppatori. È ottimo mostrare alle persone come guidare un'auto, ma se nessuno sa come funziona, cosa succede quando si guasta?
Differenze minori tra documentazione di prodotto e software¶
Esistono alcune differenze da considerare tra la documentazione di prodotto e software:
Documentazione software e di prodotto: pubblico target e persona¶
La documentazione di prodotto si rivolge a un unico pubblico: l'utente. Presuppone che l'utente non abbia conoscenze tecniche, comunicando in linguaggio semplice con minimo gergo tecnico. Come un apprendistato tecnico rispetto a una laurea universitaria, insegna alle persone come fare le cose, con meno enfasi sulla conoscenza teorica o concettuale.
La documentazione software è destinata ad amministratori IT, ingegneri e sviluppatori. Copre il design e l'architettura del software, istruzioni di configurazione da riga di comando, supporto API e integrazione, gestione dati e reportistica, topologia di rete – fondamentalmente gli ingranaggi che fanno funzionare la macchina. Questi documenti costituiscono una fonte unica di verità (SSOT) a cui il personale IT può fare riferimento durante il monitoraggio e la risoluzione dei problemi dell'applicazione software.
Documentazione software e di prodotto: frequenza di aggiornamento¶
La documentazione software deve essere costantemente aggiornata quando nuovi commit vengono uniti al canale di rilascio principale. La documentazione software deve evidenziare nuove funzioni e comandi, e deprecare le vecchie funzionalità. Nuove dipendenze o modifiche dovrebbero essere documentate, e il supporto delle funzionalità su tutte le piattaforme target dovrebbe essere chiarito – come una funzionalità che funziona su Windows, ma non su Linux.
La documentazione di prodotto necessita di aggiornamenti solo quando le modifiche al software sottostante provocano un cambiamento nel flusso di lavoro o nell'usabilità. Se uno sviluppatore modifica il codice per un gateway di pagamento, ma il processo di pagamento per gli utenti rimane lo stesso, non sono necessari aggiornamenti.
Questo mostra una gerarchia naturale per la documentazione del prodotto software. La documentazione tecnica del software costituisce la base, e la successiva documentazione di prodotto si basa su questo fondamento. Pertanto, l'attenzione dovrebbe essere rivolta alla creazione di un'ottima documentazione software, poiché genera una documentazione di prodotto ancora migliore.
Esempi di framework di formattazione per documentazione di prodotto e software¶
Una documentazione di prodotto potrebbe seguire questo framework:
- Nome del prodotto
- Panoramica dello scopo del prodotto
- Guida alla configurazione
- Spiegazione e immagini della funzionalità 1
- Spiegazione e immagini della funzionalità 2
- Link di supporto clienti
Analogamente, una documentazione software potrebbe seguire questo framework:
- Nome del software
- Panoramica dello scopo del software
- Dipendenze software
- Guida all'installazione
- Spiegazione e immagini della funzione 1
- Spiegazione e immagini della funzione 2
- Link di supporto tecnico
Chiaramente, questi due tipi di documentazione sono strettamente correlati tra loro e seguono una struttura simile. Questo significa che i team di prodotto e software hanno molto da imparare l'uno dall'altro e hanno un grande potenziale quando collaborano sulla documentazione.
I team di documentazione di prodotto e software possono completarsi a vicenda¶
Ci sono forti somiglianze tra la documentazione di prodotto e software. Questo solleva la domanda: i team di prodotto e software possono lavorare insieme?
Sì, possono, e dovrebbero!
I team software comprendono il gergo tecnico e le tecnologie sottostanti. I team di prodotto comprendono ciò che gli utenti vedono, vogliono e di cui hanno bisogno; l'esperienza utente. Gli scrittori di documentazione software possono fornire informazioni tecniche dettagliate, e gli scrittori di documentazione di prodotto possono semplificare i dettagli tecnici per il consumo da parte di un pubblico non esperto.
Immagina di provare a spiegare qualcosa in termini semplici, senza avere la comprensione di alto livello necessaria per formulare qualcosa che una persona comune capirebbe. Questo è ciò che accade quando la documentazione di prodotto viene creata prima della documentazione software.
Cos'è la meccanica quantistica? Il gatto di Schrödinger è probabilmente il primo pensiero che ti viene in mente! Ma cosa c'entrano i gatti con la meccanica quantistica? Per l'utente, non è importante. Per un fisico, significa tutto.
Inizia con la documentazione software, finisci con una migliore documentazione di prodotto in Docsie¶
Per concludere, ci sono molti vantaggi nell'utilizzare la documentazione software come modello per la successiva documentazione di prodotto. La documentazione software dovrebbe fungere da fonte unica di verità per il personale IT e gli scrittori di documentazione di prodotto. Dopo che è stata scritta, gli autori della documentazione di prodotto avranno la chiarezza e la comprensione necessarie per semplificare e condividere conoscenze facili da usare con i clienti, con una guida tecnica per la revisione e il controllo qualità.
Semplicemente, iniziando con un'ottima documentazione software, i tuoi scrittori possono creare una documentazione di prodotto ancora migliore!
Inizia a creare documentazione che aiuti i tuoi clienti a fare di più. Iscriviti al nostro piano Startup (gratis per sempre!) e offri la gioia della documentazione con Docsie!