What style of documentation should product managers use in order to communicate the appropriate message?

La documentazione è una delle componenti più cruciali e sottovalutate di qualsiasi progetto open source, e non dovrebbe essere presa alla leggera.

In generale, molti progetti open source non ricevono adeguata attenzione semplicemente perché i loro autori non sono realmente interessati, non sono capaci o non hanno il tempo di creare un ambiente di documentazione efficace per le loro API e prodotti.

Anche se la tua applicazione fosse eccellente, se la documentazione è inadeguata, gli utenti non potranno beneficiare del suo utilizzo.

Inoltre, anche se fossero costretti a utilizzarla per qualsiasi motivo, non riusciranno a farlo in modo efficace o nel modo in cui vorresti.

Imparare a produrre una documentazione eccellente richiede un impegno significativo, così come esaminare periodicamente altri progetti di documentazione. Fidati di me - come persona che ha creato numerosi documenti per Docsie - se stai sviluppando codice che verrà utilizzato da qualcun altro, e in particolare se queste persone sono i tuoi clienti, il tuo prodotto dovrebbe essere ben documentato, formattato e presentato in modo dinamico.

Qual è la differenza tra tutorial, guide pratiche, spiegazioni e riferimenti?¶

Molte persone credono erroneamente che queste quattro espressioni si riferiscano alla stessa cosa. In realtà, esprimono significati diversi. Questi diversi tipi di documentazione sono essenziali e presentano differenze chiave:

Documentazione Tutorial: Documentazione basata sulle informazioni orientata alla formazione.

Guide Pratiche/Manuali Utente: Documentazione che spiega come risolvere problemi specifici attraverso una serie di passaggi per raggiungere un obiettivo preciso.

Documentazione Esplicativa: Documentazione in forma di articolo progettata per aiutare l'utente/lettore a comprendere meglio un prodotto attraverso varie spiegazioni e contesto.

Documentazione di Riferimento: Progettata per informare l'utente sulla descrizione di vari aggiornamenti e utilizzi di nuove funzionalità. Questa documentazione può essere molto "grezza" nella forma di documentazione per sviluppatori, ma può anche essere tradotta in note di rilascio più user-friendly facilmente comprensibili dall'utente finale.

Motivi per produrre documentazione di alta qualità¶

Prima di procedere, è fondamentale comprendere perché una documentazione competente è un requisito molto importante ma sottovalutato nella società odierna. La disponibilità di documentazione completa e ben scritta è uno dei criteri più importanti per ottenere un'ampia adozione, in particolare nei progetti open source dove praticamente ogni azione è disponibile al pubblico e dove tali attività giocano un ruolo cruciale nel successo del progetto.

Diamo un'occhiata ai motivi più importanti per scrivere una documentazione efficace.

Consente di creare una migliore esperienza di onboarding per i clienti¶

Quando fornisci una documentazione adeguata sul tuo prodotto ai clienti, li aiuti a sentirsi più a loro agio con il tuo prodotto e protetti dalle sue linee guida specifiche. Per far sì che questo accada, devi:

1. Assicurarti che la documentazione del prodotto sia visibile e facilmente accessibile, tramite link in-app o all'interno di una piattaforma di documentazione ricercabile.

2. Assicurarti che sia ben scritta e aiuti il cliente a trovare rapidamente e facilmente la propria risposta

Un consiglio è scrivere la documentazione una sola volta, e verrà consultata ripetutamente quando nuovi clienti entreranno a far parte della tua azienda.

Di conseguenza, ci saranno meno richieste di supporto¶

I clienti che leggono e comprendono la tua documentazione hanno maggiori probabilità di acquistare i tuoi prodotti. Quando i clienti non riescono a capire qualcosa, può essere molto frustrante e potrebbero iniziare a incolpare il tuo prodotto.

Alcuni clienti potrebbero contattare immediatamente il team di supporto se incontrano un problema; tuttavia, se la documentazione è attraente, facilmente accessibile e comprensibile, saranno in grado di risolvere i propri problemi senza consultarti, il che li farà sentire più autonomi.

Aiuta a supportare il tuo stesso team¶

Una solida knowledge base può essere utilizzata anche per aiutare i membri del tuo team. Il tuo team interno dovrebbe essere informato su nuove funzionalità, roadmap pianificate, documentazione API e tutto ciò che è necessario per mantenere tutti sulla stessa pagina.

Istruzioni passo-passo su come scrivere una documentazione efficace¶

Scrivere il contenuto del documento e organizzare questa attività sono due compiti completamente distinti dal determinare quale tono utilizzare e come garantire che la documentazione sia comprensibile. Come affermato da O'Reilly, ci sono 8 regole per una buona documentazione:

1. Creare documentazione invitante per il lettore.

2. Produrre documentazione completa che copra tutte le aree del progetto.

3. Produrre materiale facile da scorrere e comprendere.

4. Creare documentazione che dimostri come utilizzare il prodotto attraverso casi di studio.

5. Scrivere documentazione che contenga ripetizioni dove necessario.

6. Scrivere documentazione aggiornata

7. Scrivere documentazione a cui è facile contribuire

8. Scrivere documentazione facile da trovare e comprendere

Questi elementi riguardano principalmente il contenuto. Di seguito, spiegheremo il "come" strutturare queste informazioni in sei passaggi:

Decidi cosa documentare¶

Prima di iniziare, prenditi del tempo per considerare che tipo di documentazione produrrai: è un tutorial, un documento di riferimento, un manuale di istruzioni o una spiegazione?

Tieni presente che la natura del tuo prodotto influenzerà direttamente il tipo di documentazione che dovrai creare.

Crea una struttura¶

Costruisci prima una base per la tua documentazione. All'inizio può essere molto piccola e comprendere solo pochi gruppi, ma nel tempo l'intera piattaforma su cui stai costruendo inizierà a crescere in dimensioni e complessità. Dovresti rivedere regolarmente la tua struttura organizzativa.

Ricorda che sei l'insegnante e sei responsabile di come i tuoi studenti apprendono. Saranno guidati dalle tue istruzioni; quindi, più tempo dedichi alla struttura, più successo avranno i tuoi studenti.

Utilizza sempre tecniche multimediali efficaci¶

Assicurati di utilizzare video, disegni e stili vari e inserirli direttamente nella documentazione. Docsie permette di incorporare questi elementi nella piattaforma per semplificare il processo.

Non solo aiuteranno i clienti a comprendere meglio le informazioni che fornisci, ma offriranno anche un'ottima ottimizzazione per i motori di ricerca, portando a un maggior numero di lead di alta qualità grazie alla documentazione dinamica.

Assicurati che sia ricercabile¶

Ci sono differenze nelle capacità di ricerca delle diverse piattaforme di knowledge base: alcune offrono solo ricerche di base senza possibilità di approfondire le segmentazioni (tecnicamente va bene se non hai migliaia di file), mentre altre offrono opzioni di query che ti permettono di cercare non solo nei documenti ma anche nei nomi utente.

Tuttavia, una cosa è fondamentale: dovresti utilizzare uno strumento che ti permetta di cercare rapidamente. Una funzione di ricerca integrata nell'app rende semplice cercare file e ottenerne un'anteprima senza uscire dall'app.

Docsie ti permette di avere una navigazione ricercabile dinamicamente per informazioni facilmente accessibili.

Cerca costantemente di migliorare e aggiornare¶

Creare e utilizzare documenti è difficile perché vengono rapidamente dimenticati dalle persone che li hanno generati o ne hanno beneficiato. I documenti affrontano anche varie sfide durante il loro percorso.

Con il passare del tempo, la struttura delle cartelle assume l'aspetto di un cimitero, poiché la documentazione più vecchia tende a rimanere in una posizione inferiore sullo schermo.

Assicurati quindi di rivedere la tua vecchia documentazione e apportare miglioramenti, e incoraggia i tuoi colleghi a fare lo stesso di tanto in tanto. Docsie ti permette di creare aggiornamenti attraverso il nostro sistema avanzato di versioning, semplice e facile da usare.

Considerazioni finali:¶

Vuoi saperne di più su come scrivere una documentazione efficace? Per i professionisti della documentazione software, ci sono tantissimi blog e informazioni da trovare qui.