Close

Creazione di una documentazione migliore

Hai appena avviato un progetto e ora sei in difficoltà con la consegna della documentazione (ossia caos totale).

A prima vista ti sembra una missione impossibile? Non preoccuparti: siamo qui per darti una mano! Di seguito troverai la documentazione sulla documentazione [(wink)] , una guida passo passo con suggerimenti degli esperti che ti guidano lungo il percorso. Procediamo!


Perché è importante per me?

In parole semplici, la documentazione aiuta le persone a svolgere le attività. Tuttavia, come per la maggior parte delle cose inspiegabilmente straordinarie, fa molto più di questo. La documentazione aiuta utenti e team a:

Riduci l'impegno mentale

Portare a termine il lavoro senza scervellarsi e con il minimo sforzo possibile.

Crea coerenza

Assicurarsi che le stesse informazioni, gli stessi processi e gli stessi piani vengano utilizzati dai lettori in modo coerente.

Riduci al minimo il carico di lavoro

Effettuare l'onboarding dei colleghi del team in modo rapido ed efficiente affinché possano essere subito operativi.

Migliora il branding aziendale

Esprimere l'importanza e il valore che clienti esterni e dipendenti interni assumono per te fornendo loro assistenza e sostegno.

Se non offri valore, nessuno ti considera. Hai il compito di definire il modo in cui i tuoi lettori interpretano le informazioni che ricevono da te e di far sì che comprendano chiaramente il motivo per cui sono importanti per loro.

Cosa si intende per documentazione?

La documentazione è esattamente ciò che pensi che sia: un insieme di documenti. Una bussola per il tuo utente finale medio. Un playbook per il Software Engineer che è in te. In un ambito più tecnico, la documentazione è di solito costituita da testo o illustrazioni che accompagnano un software. Questi documenti fungono da guida di riferimento che spiega come funziona e come utilizzarlo. I team software possono fare riferimento alla documentazione quando parlano di requisiti del prodotto, note di rilascio o specifiche di progettazione. I team tecnici possono utilizzare i documenti per fornire i dettagli del codice, creare API e registrare i propri processi di sviluppo software. La documentazione esterna assume spesso la forma di manuali e guide utente per amministratori di sistema, team di assistenza e altri utenti finali.

Tutta la documentazione si propone di raggiungere due obiettivi principali:

1. Informare gli utenti

2. Consentire agli utenti di svolgere con successo una determinata attività

Nel processo di creazione della documentazione, inizia definendo l'argomento di interesse e l'obiettivo, in modo da aiutare il pubblico di destinazione a capire subito cosa sta leggendo.

Tipi di documentazione

Prima abbiamo accennato al fatto che la documentazione è disponibile in tutte le forme e dimensioni, interne ed esterne. Diversi tipi di documenti richiedono voce, tono, formattazione, collaboratori, pubblico e contenuti diversi. Ecco i tipi più comuni:



Documentazione interna
illustrazione-documentazione-team

Documentazione sul team

La documentazione per il team aiuta a chiarire il lavoro svolto in modo da rendere efficace la collaborazione tra team. Questi documenti possono essere piani di progetto, programmazioni del team, report di stato, note delle riunioni e qualsiasi altra cosa di cui un team potrebbe aver bisogno per lavorare in modo efficace ed efficiente. Si tratta di un tipo di documentazione dettagliata, che permette a tutti di essere sulla stessa lunghezza d'onda.

illustrazione-documentazione-riferimento

Documentazione di riferimento

La documentazione di riferimento fornisce all'azienda conoscenze su argomenti, processi e policy importanti. Potrebbe trattarsi di policy create dal reparto delle risorse umane, di processi legali per l'assunzione di vendor esterni o di articoli delle procedure per definire i vantaggi aziendali. Ricorda che la documentazione di riferimento è scritta da un piccolo gruppo di persone per un pubblico ampio e diversificato, quindi è importante che i contenuti siano assimilabili.

illustrazione-documentazione-progetto

Documentazione del progetto

La documentazione del progetto è, naturalmente, specifica per il progetto e offre la struttura necessaria allo sviluppo del prodotto. Include proposte, documenti sui requisiti del prodotto, linee guida o schizzi di progettazione, roadmap e altre informazioni pertinenti che sono necessarie per lo sviluppo, con i contributi di project manager, ingegneri, progettisti e altro ancora.



DOCUMENTAZIONE ESTERNA
illustrazione-documentazione-isistema

Documentazione di sistema

La documentazione di sistema descrive in dettaglio il codice, le API e altri processi che indicano a sviluppatori e programmatori quali tipi di metodi e funzioni possono essere utilizzati nello sviluppo di software specifico, nonché le limitazioni e i requisiti. I frammenti di codice, come le chiamate e le risposte API di esempio, sono fondamentali per questo tipo di documentazione.

illustrazione-documentazione-utente finale

Documentazione per l'utente finale

La documentazione per l'utente è spesso il tipo di documentazione più visibile. È importante che sia facile da leggere e comprendere, e aggiornata con ogni nuova versione del software. Include documenti Leggimi, guide all'installazione, guide per l'amministratore, knowledge base sui prodotti e tutorial (i più utili di tutti). Inoltre, analogamente alla documentazione di riferimento, è redatta da un piccolo gruppo di autori per un ampio gruppo di persone, quindi è importante che i contenuti siano assimilabili.

Fornire degli esempi nella documentazione offre un valore enorme al tuo gruppo di destinatari. Aiutano i lettori a comprendere concetti e idee, oltre a costituire una garanzia della tua conoscenza effettiva degli argomenti trattati.

Creazione della documentazione

L'obiettivo finale è garantire che la documentazione sia utile per il lettore. Di seguito troverai una documentazione in formato tutorial che ti semplifica un po' il compito di creare la tua documentazione (ossia metadocumentazione!).

1. Conduci le ricerche

Cosa devono sapere gli utenti sul tuo prodotto, progetto o sull'API? Usa lo strumento di analisi per vedere quali sono i contenuti cercati, navigare nei forum della community online e nei gruppi di discussione, nonché condurre test di usabilità e ricerche sugli utenti. Inoltre, è importante che anche tu conosca il prodotto e che sia in grado di spiegare facilmente le domande degli utenti, le nuove funzioni e i flussi di lavoro.

2. Inizia

Indica in modo chiaro gli argomenti trattati nella documentazione e perché sono importanti per i lettori.

3. Acquisisci i dettagli

Crea una struttura e prepara i contenuti. Scrivi utilizzando il tono e la voce appropriati (dando un tocco umano) per il tuo pubblico e sii coerente e conciso. Comunica i dettagli importanti in modo chiaro.

4. Stabilisci il formato

Organizza la pagina in modo che sia facile seguirla dall'inizio alla fine. Elimina i contenuti ridondanti e suddividi quelli lunghi con elementi visivi come diagrammi, screenshot e immagini.

5. Rivedi

Ottieni un feedback completo. Assicurati che i revisori comprendano l'obiettivo della documentazione. Questo contribuirà a far emergere eventuali testi pochi chiari o passaggi mancanti.

6. Pubblica

Dopo le revisioni e le modifiche, è pronta per il lancio. Pubblica il tuo lavoro e tieni le orecchie aperte per eventuali feedback e commenti. La documentazione è qualcosa di dinamico.

Consigli d'oro

Come puoi vedere, creare una documentazione non significa semplicemente mettere insieme una serie di parole e istruzioni. C'è del metodo in questa follia. Ricorda questi principi guida prima, durante e dopo aver creato la documentazione:

Sii sintetico

La documentazione deve contenere la giusta quantità di informazioni affinché il lavoro sia portato a termine senza creare un ticket di assistenza. Fornisci i punti chiave e la possibilità per i lettori di ottenere ulteriori approfondimenti.

Usa le immagini

Le immagini sono fondamentali per la comprensione. La progettazione del prodotto, gli esempi di codice, le demo all'interno del prodotto, gli screenshot e le esercitazioni video svolgono un ruolo importante nell'aiutare i lettori a comprendere appieno il concetto, le istruzioni o le cose da fare. Inoltre, tieni presente anche il layout, la leggibilità e la suddivisione in porzioni facilmente assimilabili.

Conosci il tuo pubblico

Immedesimati nell'utente. Conosci il tuo lettore, esplora il suo percorso come utente del tuo prodotto e della tua documentazione. Questo dovrebbe sempre guidarti nella scelta dei contenuti e del modo in cui li scrivi.

Inizia con entusiasmo

La documentazione migliore è chiara, breve, informativa e, soprattutto, offre valore aggiunto al pubblico di destinazione. Esplora il software di collaborazione in team come Confluence per la tua documentazione e dedica meno tempo a cercare e più tempo a concludere.

Scopri di più