Documentazione tecnica del software

Documentazione tecnica del software

In questo articolo, approfondiamo il ruolo cruciale che la Documentazione tecnica del software svolge nello sviluppo software. Ti guideremo attraverso i vari tipi di documentazione, condivideremo le best practice per creare documenti chiari e concisi e introdurremo strumenti che possono semplificare il processo.

Cos’è la Documentazione tecnica del software?
La Documentazione tecnica del software nell’ingegneria del software è il termine generico che comprende tutti i documenti e i materiali scritti relativi allo sviluppo di prodotti software. Tutte le soluzioni software, siano esse create da un piccolo team o da una grande azienda, richiedono vari tipi di documenti durante l’intero ciclo di vita dello sviluppo software (SDLC – software development life cycle).

Documentazione del progetto nelle diverse fasi del ciclo di vita dello sviluppo del software (SDLC)

La Documentazione tecnica del software spiega le funzionalità del prodotto, aiuta a pianificare le attività del progetto e fornisce chiarezza sugli obiettivi finali.

Alcune persone pensano che la Documentazione tecnica del software sia creata solo per i team di sviluppatori, ma non è del tutto vero. Sebbene contenga sicuramente molte informazioni tecniche, in realtà aiuta diversi gruppi di stakeholder a essere sulla stessa lunghezza d’onda e a condividere una comprensione comune dei risultati attesi. Inoltre, come spiegheremo più avanti, vengono creati diversi tipi di Documentazione tecnica del software per pubblico diverso e, a volte, non si tratta di specialisti della tecnologia (ad esempio, guide per l’utente finale).

Un altro tipo di Documentazione tecnica del software che vale la pena esplorare è la documentazione del codice . Il nostro articolo dedicato esplora questo tipo di documentazione in dettaglio.

Approcci Agile e Waterfall alla Documentazione tecnica del software
I tipi di documentazione che il team produce e il suo ambito dipendono dall’approccio di sviluppo software scelto. Ce ne sono due principali: Agile e Waterfall. Ognuno di questi è unico in termini di documentazione tecnica di accompagnamento.

Approccio Waterfall (a cascata)
L’ approccio Waterfall è un metodo lineare in cui si può procedere alla fase successiva solo quando si ha terminato quella precedente. I team che utilizzano Waterfall dedicano una quantità ragionevole di tempo alla pianificazione del prodotto nelle fasi iniziali del progetto. Creano una panoramica completa degli obiettivi e degli scopi principali e pianificano in dettaglio come sarà il processo di lavoro.

Stadi di cascata – waterfall
Le fasi di avvicinamento alla cascata

I team Waterfall si sforzano di comporre una documentazione dettagliata prima che inizi qualsiasi fase di progettazione. Una pianificazione attenta funziona bene per progetti con poche o nessuna modifica in corso, poiché consente una stima precisa del budget e dei tempi. Tuttavia, la pianificazione Waterfall si è dimostrata inefficace per lo sviluppo a lungo termine, poiché non tiene conto di possibili modifiche e imprevisti al volo.

Approccio agile
L’ approccio Agile si basa sul lavoro di squadra, sulla stretta collaborazione tra sviluppatori, stakeholder aziendali e clienti finali, sulla flessibilità e sulla capacità di rispondere rapidamente ai cambiamenti. I mattoni fondamentali dello sviluppo Agile sono le iterazioni : ciascuna di esse include fasi quali pianificazione, progettazione, sviluppo, ecc.

Sviluppo software agile
Ciclo di sviluppo agile

L’approccio Agile non richiede una documentazione completa all’inizio. I manager non hanno bisogno di pianificare troppo in anticipo perché le cose possono cambiare man mano che il progetto evolve. Ciò consente una pianificazione just-in-time.

Uno dei valori dell’Agile Manifesto è “software funzionante anziché documentazione completa”. Mentre Agile pone maggiore attenzione al prodotto in sé, anche le formalità non dovrebbero essere ignorate. Quindi l’idea è di produrre documentazione con informazioni essenziali per andare avanti quando ha più senso.

Oggi, Agile è la pratica più comune nello sviluppo software: secondo il 17° State of Agile Report , il 71 percento delle aziende lo usa nel proprio SDLC. Quindi ci concentreremo sulle pratiche di documentazione relative a questo metodo.

Pianificazione software e Documentazione tecnica del software
Documentazione e pianificazione del software – Documentazione tecnica del software

Tipi di Documentazione tecnica del software
L’obiettivo principale di una documentazione efficace è garantire che gli sviluppatori e gli altri stakeholder lavorino insieme per raggiungere gli obiettivi del progetto. Esistono diversi tipi di documentazione software per raggiungere questo obiettivo.

Tipi di documentazione
Documentazione tecnica del software più comunemente utilizzata nei progetti Agile

Tutta la documentazione software può essere suddivisa in due categorie principali:

• Documentazione del prodotto
• Documentazione del processo

La documentazione del prodotto descrive la soluzione che viene sviluppata e fornisce istruzioni su come interagire con essa. In generale, la documentazione del prodotto include requisiti, specifiche tecniche, logica aziendale e manuali. Esistono due tipi principali di documentazione del prodotto:

• La documentazione di sistema descrive il sistema stesso e le sue parti. Include documenti sui requisiti, decisioni di progettazione, descrizioni di architettura, codice sorgente del programma, ecc.
• La documentazione utente comprende manuali preparati principalmente per gli utenti finali del prodotto e gli amministratori di sistema. Include tutorial, guide utente, manuali di risoluzione dei problemi, istruzioni di installazione e così via.

La documentazione di processo descrive come lavorano i team quando sviluppano software. È come una guida dettagliata che elenca le procedure che i membri del team seguono durante l’SDLC, gli strumenti che usano e le regole che devono rispettare. Questa documentazione aiuta tutti a capire come vengono fatte le cose, assicura che il processo sia coerente e rende più facile per i nuovi membri del team mettersi al passo.

Esempi comuni di documenti correlati ai processi sono arretrati, roadmap, standard di codifica e test, report, verbali di riunione, checklist di rilascio e persino corrispondenza commerciale.

Analizziamo ora più in dettaglio ciascuna categoria di documentazione.

Prodotto: Documentazione di sistema
La documentazione di sistema fornisce una panoramica della soluzione e aiuta ingegneri e stakeholder a comprendere la tecnologia sottostante. Di solito copre:

• Requisiti del prodotto,
• Progettazione UX,
• Architettura,
• codice sorgente
• Attività di controllo qualità, ecc.

Vale la pena sottolineare che questo elenco non è esaustivo. Esaminiamo i principali documenti di sistema.

Documento sui requisiti del prodotto (PRD)
Un documento sui requisiti di prodotto o PRD fornisce informazioni sulla funzionalità e sul comportamento del sistema. In genere, i requisiti sono dichiarazioni su cosa dovrebbe fare un sistema e come dovrebbe funzionare.

Una buona prassi è scrivere un documento sui requisiti utilizzando un singolo modello coerente a cui tutti i membri del team aderiscano. Il modulo di una pagina web ci aiuterà a mantenere il documento conciso e a risparmiare tempo nell’accesso alle informazioni. Ecco un esempio di PRD di una pagina web per comprenderne i vari elementi. Tuttavia, ricordiamo che questo non è l’unico modo per compilarlo.

Esempio di Documentazione tecnica del software
Esempio di Documentazione tecnica del software interazione utente e progettazione
Esempio di documentazione tecnica: un documento di requisiti software di una pagina web creato utilizzando Atlassian Confluence , il software di collaborazione sui contenuti

Ecco i punti principali da includere nel documento sui requisiti del prodotto.

Ruoli e responsabilità . Iniziamo con le informazioni sui partecipanti al progetto, tra cui un product owner, i membri del team e altri stakeholder chiave. Questi dettagli chiariranno le responsabilità e comunicheranno i ruoli di ciascun membro del team.

Obiettivi del team e obiettivi aziendali . Definiamo brevemente gli obiettivi più importanti del progetto.

Contesto e adattamento strategico . Forniamo una breve spiegazione dell’obiettivo strategico delle tue azioni. Perché stai realizzando il prodotto? Come si allineerà agli obiettivi dell’azienda? Qual è l’ adattamento al mercato ?

Ipotesi . Crea un elenco di ipotesi tecniche o aziendali che intendi convalidare o invalidare durante il progetto.

Storie utente . Elenca o collega le storie utente necessarie per il progetto. Scritta dal punto di vista dell’utente finale, una storia utente è una breve descrizione delle azioni del cliente e dei risultati che desidera ottenere.

Criteri di accettazione . Sono le condizioni che indicano che una storia utente è completata. Lo scopo principale dei criteri di accettazione è definire un risultato soddisfacente per uno scenario di interazione dal punto di vista dell’utente finale.

Per saperne di più, consulta i nostri articoli dedicati ai criteri di accettazione e ai test di accettazione dell’utente .

Che cosa sono i test di accettazione dell’utente (UAT) e perché il tuo prodotto ne ha bisogno.

Che cosa sono i test di accettazione dell’utente

Interazione e progettazione dell’utente . Spesso, il progetto esatto viene creato dopo aver composto il PRD, quindi puoi semplicemente includere una guida generale o schizzi approssimativi del progetto del prodotto. In seguito, quando i progetti effettivi sono disponibili, puoi collegarli al PRD.

Domande . Mentre il team risolve i problemi durante l’avanzamento del progetto, inevitabilmente sorgono molte domande. Una buona pratica è quella di registrare tutte queste domande e tenerne traccia.

Fuori dall’ambito (non in corso) . Elenchiamo le cose che non abbiamo intenzione di fare durante questo progetto per stabilire dei limiti chiari e prevenire l’espansione dell’ambito. Possono essere funzionalità correlate al prodotto ma non sviluppate come parte di questo particolare progetto. Ad esempio, se creiamo un sito Web di e-commerce, un’app mobile personalizzata potrebbe essere un elemento fuori dall’ambito. Possiamo anche specificare servizi aggiuntivi qui come la manutenzione post-progetto per chiarire le tue responsabilità.

Notiamo che oltre al PRD, altri tipi di documenti correlati ai requisiti vengono creati per scopi distinti. I più notevoli sono il Business Requirements Document (BRD) e il Software Requirements Specification (SRS). In sintesi, la differenza fondamentale tra i due è che il BRD si concentra sulla prospettiva aziendale, il PRD delinea i requisiti del prodotto dal punto di vista dell’utente e del mercato, mentre l’SRS fornisce un progetto tecnico dettagliato di come il software dovrebbe funzionare per soddisfare tali requisiti.

Documento sui requisiti aziendali spiegato: il tuo progetto per il successo del progetto
BRD spiegato

Documentazione sulla progettazione dell’esperienza utente
La progettazione dell’esperienza utente (UX design) inizia nella fase di pianificazione e procede attraverso tutte le fasi di sviluppo, comprese le fasi di test e post-rilascio. Il processo di progettazione UX include ricerca, prototipazione, test di usabilità e la fase di progettazione vera e propria, durante la quale vengono prodotti molti documenti e risultati.

La fase di ricerca comporta la raccolta di informazioni sugli utenti e sul contesto in cui interagiranno con il prodotto. Le tecniche applicate includono interviste agli utenti , sondaggi, osservazioni e analisi di mercato. L’obiettivo è comprendere le esigenze, i comportamenti, i punti dolenti e le motivazioni degli utenti. Implica lo sviluppo:

• personaggi utente,
• scenari utente e
• mappe degli scenari.

Le user personas rappresentano le caratteristiche chiave dei potenziali utenti del prodotto, concentrandosi su comportamento, schemi di pensiero e motivazione. Aiutano a definire i segmenti di clientela e ad adattare la funzionalità del prodotto e le future strategie di marketing a diversi gruppi di utenti.

Uno scenario utente è un documento che descrive i passaggi che una user persona intraprenderà per portare a termine un’attività specifica. Gli scenari utente si concentrano su ciò che un utente farà, piuttosto che delineare il processo di pensiero.

Le mappe degli scenari vengono utilizzate per compilare gli scenari utente esistenti in un singolo documento. Le mappe degli scenari mostrano tutti i possibili scenari disponibili in un dato momento per ogni singola funzione, nonché i passaggi di scenario intersecanti.

Durante la fase di prototipazione, gli UX designer lavorano con i deliverable della fase di ricerca. Sviluppano rappresentazioni interattive del prodotto finale per creare e testare i concept di design. Alcuni documenti comuni prodotti in questa fase sono

• Mappe del sito
• Wireframe (struttura a reticolo)
• Modelli
• Prototipi
• Mappe del flusso/ percorso dell’utente
• Rapporti sui test di usabilità

Una mappa sito/prodotto è uno schema visivo che rappresenta la connessione tra tutte le pagine di un prodotto. Aiuta il team a visualizzare la struttura di un sito web o di un’app e le connessioni tra le pagine/funzioni. Creare una mappa sito è una parte dell’organizzazione dell’architettura delle informazioni .

Esempio di struttura della mappa del sito

Le mappe del flusso utente o del percorso utente visualizzano i passaggi che un utente dovrebbe compiere mentre interagisce con tutte le parti del prodotto. Di solito, lo schema include tutte le pagine, le sezioni, i pulsanti e le funzioni fornite per mostrare la logica del movimento dell’utente.

Schema del flusso utente per la domanda di ricerca di lavoro.

I wireframe sono i progetti per le future UI. In pratica, i wireframe sono schemi che mostrano come disporre gli elementi sulla pagina e come dovrebbero comportarsi, ma senza dettagli su come dovrebbero apparire quegli elementi.

Esempio di wireframe per l’app mobile

I mock-up , il passo successivo della creazione del design, sono immagini statiche che rappresentano l’aspetto e la sensazione reali di un prodotto finale.

Un prototipo è un mock-up con cui puoi interagire: cliccare su alcuni pulsanti, navigare tra diverse pagine e così via. Un prototipo può essere creato in uno strumento di prototipazione come Sketch o MockFlow . Utilizzando i template, i designer UX possono creare mock-up interattivi nelle prime fasi di sviluppo da impiegare per i test di usabilità.

Prototipazione, spiegata: perché e come creare una versione campione di un prodotto

Progettazione UX
prototipo funzionale

Prototipo funzionale: come iterare con il tuo prodotto software

Il ruolo dei test utente nella progettazione UX

Progettazione UX
Quando i prototipi vengono utilizzati nei test di usabilità, il feedback e i dati raccolti da queste sessioni vengono compilati in report.

Un report di test di usabilità aiuta a comprendere le reazioni degli utenti al prototipo, identificando i punti critici e le aree di miglioramento. Il report dovrebbe essere il più breve possibile, con esempi visivi che prevalgono sul testo.

Un altro documento di progettazione UX che spesso viene creato come ponte tra i team di progettazione e sviluppo è la guida di stile.

La guida di stile UI funge da manuale completo per la progettazione e l’implementazione dell’interfaccia utente. Garantisce coerenza nella rappresentazione visiva e nei modelli di interazione nell’intero prodotto. La guida di stile definisce come i possibili elementi UI e i tipi di contenuto dovrebbero essere progettati e organizzati. Include linee guida su:

• tavolozze di colori,
• tipografia,
• iconografia,
• layout,
• stili dei pulsanti,
• dimensioni, ecc.

Documentazione tecnica del software di architettura software
Un documento di architettura software (SAD) include le principali decisioni architettoniche prese dall’architetto della soluzione . A differenza del documento di requisiti del prodotto sopra menzionato che descrive cosa deve essere costruito, la documentazione dell’architettura riguarda come costruirlo, in che modo ogni componente del prodotto contribuirà e soddisferà i requisiti, incluse soluzioni, strategie e metodi per ottenerli.

Quindi il documento di architettura software fornisce una panoramica della struttura del prodotto e determina l’ambito completo del lavoro, coinvolgendo tutti gli stakeholder e fornendo la guida complessiva al team di sviluppo.

Non consigliamo di entrare troppo nei dettagli ed elencare tutte le attività da completare, ma piuttosto di concentrarsi sulla descrizione di alto livello.

In genere, un SAD comprende le seguenti sezioni.

Panoramica e background . Descrivi brevemente gli obiettivi principali del progetto, i problemi che stai cercando di risolvere e i risultati che vuoi ottenere.

Descrizione del prodotto . Elencare i principali requisiti funzionali e non funzionali per delineare l’ambito del progetto.

Descrizione dell’architettura di alto livello. Fornisci una panoramica dell’architettura del sistema e descrivi i componenti principali e le loro interazioni. Vale anche la pena spiegare brevemente le ragioni alla base delle decisioni architettoniche e i vincoli che hanno un impatto sul tuo approccio (ad esempio, limitazioni tecnologiche, requisiti di conformità, ecc.).

Una buona norma è quella di supportare questa sezione con diagrammi e/o altri materiali grafici per agevolare la comprensione e la comunicazione della struttura e dei principi di progettazione.

Diagramma dell’architettura dell’applicazione Web di Azure. Fonte: docs.microsoft.com

Progettazione dettagliata del sistema . Fornire una descrizione più dettagliata dei componenti chiave del sistema e del modo in cui interagiscono. Includere specifiche API e protocolli utilizzati per le comunicazioni interne ed esterne. Descrivere l’architettura dei dati, lo schema del database e l’integrità dei dati.

Strategie e soluzioni tecniche . Definire le strategie per affrontare problematiche trasversali come scalabilità, affidabilità e sicurezza (ad esempio, memorizzazione nella cache, bilanciamento del carico, tolleranza agli errori, ecc.).

Infrastruttura e distribuzione. Descrivi l’hardware e la configurazione dell’infrastruttura richiesti per distribuire ed eseguire il sistema. Includi layout di rete, specifiche del server e diagrammi di distribuzione.

Documento di progettazione tecnica (TDD) – Documentazione tecnica del software
Un documento di progettazione tecnica (TDD) , spesso definito anche specifica tecnica, fornisce informazioni dettagliate e di basso livello su come devono essere implementati i requisiti di un sistema software. Colmiamo il divario tra l’architettura del sistema e la base di codice effettiva, descrivendo in dettaglio le configurazioni specifiche, le interfacce e gli standard di codifica che gli sviluppatori seguiranno.

Un TDD include progetti di componenti, diagrammi di flusso di dati, algoritmi, endpoint API e protocolli di interazione, garantendo agli sviluppatori una guida chiara e precisa per la creazione del software.

Documentazione del codice sorgente – Documentazione tecnica del software
La documentazione del codice sorgente è un tipo di documentazione tecnica incorporata direttamente nel codice sorgente della soluzione. Spiega cosa fa il codice, come funziona e perché sono state prese determinate decisioni. Ciò può includere descrizioni di algoritmi, configurazioni e logica complessa.

La documentazione del codice sorgente si presenta sotto forma di commenti che possono variare da note su una sola riga che spiegano una particolare operazione a spiegazioni più estese, in blocchi che descrivono logiche o strutture dati più complesse.

Un codice ben documentato è più facile da gestire e correggere, poiché gli sviluppatori possono comprendere l’intento e la funzionalità del codice senza dover decifrare ogni riga.

Documentazione di garanzia della qualità
Le attività di QA sono una parte indispensabile di qualsiasi progetto di sviluppo. I documenti più comuni relativi alla garanzia della qualità sono

• Piano di gestione della qualità
• Piano di prova
• Specifiche del caso di prova
• Liste di controllo dei test

Naturalmente ce ne sono altri e descriviamo l’intero processo di controllo qualità e i suoi risultati in un whitepaper dettagliato, consultabile per maggiori informazioni.

Un piano di gestione della qualità è un analogo di un documento di requisiti dedicato ai test. Questo documento stabilisce lo standard richiesto per la qualità del prodotto e descrive i metodi per raggiungerlo. Il piano aiuta a pianificare le attività di QA e a gestire l’attività di test per i product manager, ma è utilizzato principalmente per progetti su larga scala.

Un piano di test è un documento dettagliato che delinea gli obiettivi, le risorse, l’ambito e la pianificazione delle attività di test previste in un progetto. Definisce i ruoli e le responsabilità di un team QA , specifica cosa verrà testato e cosa no, descrive i tipi di test da eseguire (come test di unità, di integrazione e di sistema) e le metodologie e gli strumenti da utilizzare.

Un piano di test include anche informazioni sulla configurazione dell’ambiente di test, sulle strategie di gestione del rischio e sui criteri per avviare e completare i test. Inoltre, elenca i deliverable previsti, come casi di test, report e log dei bug, e identifica gli stakeholder responsabili dell’approvazione del piano e dei suoi risultati.

Il presente documento funge da modello per garantire che i test siano sistematici, efficienti e allineati agli standard qualitativi e agli obiettivi del progetto.

Spesso, un piano di test viene confuso con una strategia di test , ma in realtà sono molto diversi. Mentre un piano di test è un documento a livello di progetto focalizzato su uno specifico prodotto software, una strategia di test è un documento di processo che definisce le procedure di test e gli standard adottati nell’intera azienda (lo descriveremo di seguito).

Una specifica del caso di test è un set di azioni dettagliate per verificare ogni caratteristica o funzionalità di un prodotto. Di solito, un team QA scrive un documento di specifiche separato per ogni unità di prodotto. Le specifiche del caso di test si basano sull’approccio delineato nel piano di test. Una buona pratica è quella di semplificare le descrizioni delle specifiche ed evitare ripetizioni del caso di test.

Una checklist di test è un elenco di test che devono essere eseguiti in un momento particolare. Mostra quali test sono stati completati e quanti sono falliti. Tutti i punti nelle checklist di test devono essere definiti correttamente. Prova a raggruppare i punti di test nelle checklist. Questo approccio ti aiuterà a tenerne traccia durante il tuo lavoro e a non perderne nessuno. Se aiuta i tester a controllare correttamente l’app, puoi aggiungere commenti ai tuoi punti nell’elenco.

Documentazione API – Documentazione tecnica del software
La maggior parte dei prodotti include API (Application Programming Interface) per abilitare lo scambio di dati con altri sistemi. La documentazione API contiene un elenco di tutte le API dei prodotti e delle loro specifiche. Descrive richieste, risposte, messaggi di errore e altri dettagli essenziali e informa gli sviluppatori su come interagire efficacemente con le API di sistema.

Documentazione API e perché è importantePulsante di riproduzione
Video che spiega la documentazione API e perché è importante

Prodotto: Documentazione utente – Documentazione tecnica del software
Come suggerisce il nome, la documentazione utente è creata per gli utenti del prodotto. Tuttavia, ne esistono di diversi tipi, ovvero utenti finali e amministratori di sistema. Quindi dovresti strutturare la documentazione utente in base alle diverse attività degli utenti e ai loro diversi livelli di esperienza.

Documentazione per l’utente finale – Documentazione tecnica del software
La documentazione creata per gli utenti finali dovrebbe spiegare nel modo più semplice possibile come il software può aiutare a risolvere i loro problemi. Tali istruzioni per l’utente possono essere fornite in forma cartacea, online o offline su un dispositivo.

Ecco i principali tipi di documenti utente.

La guida rapida fornisce una panoramica delle funzionalità del prodotto e fornisce linee guida di base su come utilizzarlo.

Il manuale completo include informazioni e istruzioni esaustive su come installare e utilizzare il prodotto. Elenca i requisiti hardware e software, una descrizione dettagliata delle funzionalità, linee guida complete su come ottenere il massimo da esse, esempi di input e output e possibili suggerimenti e trucchi, ecc.

La guida alla risoluzione dei problemi fornisce agli utenti finali informazioni su come trovare e risolvere possibili problemi che potrebbero sorgere durante l’utilizzo del prodotto.

Per una panoramica dettagliata, consulta il nostro articolo dedicato alla documentazione utente .

La documentazione online per l’utente finale può presentarsi sotto forma di knowledge base e includere le seguenti sezioni:

• Domande frequenti
• Video tutorial
• Assistenza incorporata
• Portali di supporto

Poiché la documentazione utente è parte dell’esperienza del cliente, è importante renderla facile da comprendere e strutturata in modo logico. Scritte in un linguaggio semplice con materiali visivi e istruzioni dettagliate incluse, le guide utente possono diventare un potente strumento di marketing e aumentare la soddisfazione e la fedeltà del cliente.

Inoltre, per fornire il miglior servizio agli utenti finali, dovresti raccogliere continuamente il feedback dei tuoi clienti. Il sistema wiki è una delle pratiche più utili per mantenere la documentazione esistente. Se utilizziamo il sistema wiki, non dovrai esportare documenti in formati presentabili e caricarli sui server. Puoi creare le tue pagine wiki utilizzando un linguaggio di markup wiki e codice HTML.

Documentazione tecnica del software per l’amministratore di sistema: guide di aiuto e manutenzione
I documenti degli amministratori di sistema sono specificamente progettati per il personale responsabile dell’installazione, della configurazione, della manutenzione e della risoluzione dei problemi dei sistemi informatici e delle reti. Forniscono linee guida e istruzioni dettagliate che garantiscono il corretto funzionamento e la sicurezza dell’infrastruttura IT.

Alcuni documenti comuni per gli amministratori di sistema sono

• guide di installazione,
• manuali di configurazione
• procedure di manutenzione (inclusi i processi di backup e ripristino),
• protocolli di sicurezza (linee guida sulle misure di sicurezza, come firewall, software antivirus e controlli di accesso),
• guide alla risoluzione dei problemi e
• piani di ripristino in caso di disastro.

Questa documentazione è fondamentale per consentire agli amministratori di sistema di gestire e salvaguardare efficacemente le risorse tecniche di un’organizzazione, garantendo continuità ed efficienza nelle operazioni IT.

Documentazione del processo – Documentazione tecnica del software
La documentazione di processo copre tutte le attività che circondano lo sviluppo del prodotto . Il valore di conservare la documentazione di processo è quello di rendere lo sviluppo più organizzato e ben pianificato.

Roadmap di prodotto agili
Le roadmap di prodotto vengono utilizzate nello sviluppo software Agile per documentare la visione, la strategia e gli obiettivi generali del progetto. Aiutano a mantenere il corso dello sviluppo in sincronia con gli obiettivi iniziali. A seconda del tipo di roadmap di prodotto, può esprimere obiettivi di alto livello, priorità delle attività , la timeline dello sprint o dettagli di basso livello.

Esistono tre tipi di roadmap di prodotto utilizzate dai team di prodotto Agile:

• roadmap strategiche,
• roadmap tecnologiche o IT
• piani di rilascio.

Una roadmap strategica è un documento strategico di alto livello che contiene informazioni generali sul progetto. Le roadmap strategiche di solito stabiliscono una visione e obiettivi a lungo termine. Nel caso dello sviluppo di prodotti Agile, una roadmap può essere organizzata in temi. I temi sono più attività che un team deve completare e sono in qualche modo collegate. Ad esempio, un tema può suonare come “migliorare la velocità di caricamento delle pagine”, che comporta molte azioni.

Raggruppare le informazioni attorno ai temi rende una roadmap altamente flessibile e aggiornabile, il che è perfetto per lo sviluppo basato su sprint. Il miglior consiglio per quanto riguarda la roadmap strategica è di includere solo le informazioni importanti. Altrimenti, rischi di trasformare la tua roadmap in uno schema goffo, difficile sia da capire che da mantenere.

Esempio di roadmap strategica del prodotto software

Una roadmap tecnologica o roadmap IT è un documento di basso livello che descrive i requisiti tecnici e i mezzi di implementazione della tecnologia. Le roadmap IT sono piuttosto dettagliate. Contengono le informazioni su ogni deliverable, spiegando il motivo di tale decisione.

Un piano di rilascio stabilisce limiti di tempo rigorosi per i rilasci. Un piano di rilascio dovrebbe concentrarsi sulle scadenze effettive senza specificare i dettagli del rilascio.

Esempio di piano di rilascio

Si consiglia vivamente di utilizzare strumenti specifici per roadmap per creare le proprie roadmap. Strumenti online come Strategic Roadmaps (in precedenza Roadmunk), ProductPlan , Visor o Aha! forniscono vari modelli per roadmap di prodotto, consentono una modifica rapida e consentono una facile condivisione tra tutti i membri del team.

Tieni presente che una roadmap, a seconda del tipo, può essere un documento di prodotto che indica i requisiti. Descrive anche il processo e guida il tuo team attraverso lo sviluppo.

Roadmap del prodotto: pianificazione del successo del prodottoPulsante di riproduzione
Consulta la nostra spiegazione per saperne di più sulle roadmap

Mentre le roadmap forniscono una panoramica di alto livello e una guida strategica, gli arretrati si concentrano sulle azioni immediate necessarie per progredire verso obiettivi più ampi.

Backlog
I backlog sono una componente fondamentale delle metodologie di gestione dei progetti Agile, in particolare in framework come Scrum. Forniscono un piano chiaro e attuabile per il team mentre lavora sul prodotto.

Scrum
Come funziona Scrum

Un backlog di progetto consiste in un elenco prioritario di attività, funzionalità, storie utente e bug (se presenti) che devono essere affrontati. Funge da fonte primaria di requisiti quando si pianificano attività di progetto. Spesso si evolve durante il ciclo di vita di un progetto man mano che si apprende di più sul prodotto e sui suoi utenti e man mano che cambiano le condizioni di mercato.

Uno sprint backlog negli approcci simili a Scrum contiene tutti i task specifici che il team di sviluppo si impegna a completare durante uno sprint. Viene creato durante la riunione di pianificazione dello sprint, quando il team seleziona gli elementi dal backlog del progetto in base alla loro priorità e alla capacità del team. Questo backlog è unico per ogni sprint ed è un documento dinamico, in quanto gli elementi possono essere suddivisi in task più piccoli, con modifiche apportate se necessario durante lo sprint per rispondere a sfide e cambiamenti.

Esistono due modi principali per organizzare il backlog. Un backlog piatto è un semplice elenco di attività da svolgere, funzionalità dopo funzionalità. Sebbene sia facile da creare, non è l’approccio migliore perché non riflette il percorso dell’utente e diventa troppo difficile da gestire man mano che cresce.

Backlog piatto vs mappa delle storie utente

Al contrario, una mappa delle storie utente organizza le storie degli utenti in un layout bidimensionale che aiuta i team a comprendere la funzionalità del prodotto, visualizzare il percorso dell’utente e stabilire le priorità degli elementi del backlog.

mappa della storia dell’utente
Un esempio di mappa di una storia utente suddivisa in release. Fonte: Netcentric

Altri documenti di processo: piani, standard, strategie, ecc.
Esistono molti altri tipi di documentazione di processo che vale la pena creare per descrivere le procedure di un’azienda o riflettere i processi specifici durante un determinato progetto.

Gli standard includono tutti gli standard di codifica, test e progettazione a cui il team aderisce durante tutto il progetto.

Piani, stime e programmi vengono solitamente creati prima dell’inizio del progetto e possono essere modificati man mano che il prodotto evolve.

Una strategia di test è un documento di alto livello che descrive l’approccio generale di test del software dell’organizzazione. Include informazioni sulla struttura del team e sulle esigenze di risorse, nonché su cosa dovrebbe essere prioritario durante il test. Una strategia di test è solitamente statica, poiché è definita per l’intero ambito di sviluppo.

Una checklist di rilascio è un elenco di attività e controlli da completare prima del rilascio del software, per garantire che nulla di importante venga trascurato.

I documenti di lavoro registrano idee e pensieri degli ingegneri durante l’implementazione del progetto. I documenti di lavoro solitamente contengono alcune informazioni sul codice, gli schizzi e le idee di un ingegnere su come risolvere i problemi tecnici. Sebbene non dovrebbero essere la principale fonte di informazioni, tenerne traccia consente di recuperare dettagli di progetto altamente specifici, se necessario.

I report riflettono il modo in cui sono stati impiegati tempo e risorse umane durante lo sviluppo. Possono essere generati su base giornaliera, settimanale o mensile.

Mentre alcuni documenti di processo sono statici e descrivono l’approccio generale dell’azienda a processi specifici (ad esempio, strategie, standard, checklist, ecc.), altri si riferiscono solo a un momento o a una fase particolare del processo (ad esempio, report intermedi). Di conseguenza, questi documenti diventano rapidamente obsoleti. Ma dovrebbero comunque essere conservati come parte dello sviluppo perché potrebbero rivelarsi utili nell’implementazione di attività simili o nella manutenzione in futuro.

Chi scrive la documentazione tecnica?
Creare documentazione tecnica per un progetto non è un compito facile. Nel processo sono coinvolti molti stakeholder diversi, ognuno dei quali apporta competenze e prospettive specifiche per garantire che la documentazione sia accurata, completa e utile.

Ecco un elenco dei ruoli chiave coinvolti e delle relative responsabilità.

Gli analisti aziendali lavorano a stretto contatto con il cliente per raccogliere e definire i requisiti aziendali che il prodotto deve soddisfare. Agiscono anche come ponte tra gli stakeholder non tecnici e il team tecnico. Garantiscono che i documenti tecnici siano allineati con gli obiettivi aziendali e siano comprensibili per gli stakeholder non tecnici. Inoltre, gli analisti aziendali contribuiscono spesso alla creazione della documentazione utente.

Gli analisti di mercato raccolgono informazioni dagli utenti finali per creare user personas e scenari utente. Inoltre, ricercano il mercato e contribuiscono ai documenti sui requisiti convalidando l’adattamento al mercato e gli obiettivi aziendali.

I project manager supervisionano il processo di documentazione per garantire che sia allineato con le tempistiche e gli obiettivi del progetto. Sono responsabili della maggior parte dei documenti di processo e dei piani correlati al progetto.

Gli architetti di soluzioni creano una documentazione completa di progettazione architettonica. Questi documenti delineano l’architettura proposta per il progetto, incluse strutture di alto livello, progettazione software e integrazione di vari componenti e sistemi esterni. Gli architetti contribuiscono anche alla creazione di roadmap tecniche e stabiliscono gli standard tecnici e le linee guida per il progetto.

Gli sviluppatori creano la documentazione del codice sorgente che descrive gli elementi software. Spiegano anche come vengono implementate le funzionalità, forniscono esempi di codice e chiariscono i complessi processi tecnici che devono essere documentati.

Gli UX designer sono coinvolti nella creazione della documentazione di progettazione UX/UI che include descrizioni dell’interfaccia, prototipi, mappe del sito, ecc.

Gli ingegneri QA contribuiscono documentando protocolli di test, risultati e configurazioni. Garantiscono che la documentazione rifletta i passaggi necessari per testare efficacemente il software e segnalare i bug.

I redattori tecnici sono principalmente responsabili della stesura e della modifica della documentazione. Collaborano con esperti tecnici per raccogliere dettagli accurati e presentarli in un formato di facile utilizzo.

Strumenti per la documentazione del software
Un elenco così lungo di documenti tecnici può sembrare intimidatorio, ma non devi scriverli su carta, né crearli da zero. Ci sono molti strumenti specializzati che ti aiuteranno a fare il lavoro pesante.

Strumenti di uso generale
Esistono innumerevoli strumenti collaborativi per i team di sviluppo software. Questi possono aiutare a dichiarare requisiti, condividere informazioni e documentare funzionalità e processi.

Atlassian Confluence è lo strumento di progetto collaborativo più popolare che ha l’intero ecosistema per la gestione dei requisiti di prodotto e la scrittura della documentazione. Confluence è noto per un sistema wiki stabile e un’interfaccia di gestione delle storie utente efficiente.

Document 360 è una piattaforma di documentazione software/knowledge base self-service progettata per i prodotti Software-as-a-Service.

bit.ai è uno strumento per la creazione di documentazione collaborativa, l’archiviazione, la condivisione di dati e l’utilizzo di un sistema wiki. La documentazione è interattiva, il che significa che gli sviluppatori possono incorporare blocchi o frammenti di codice direttamente nel documento e condividerli con un clic. Una volta terminata la modifica della documentazione, è possibile salvarla in formato PDF o markdown e pubblicarla su qualsiasi altra piattaforma.

Github non ha bisogno di presentazioni, tranne per coloro che vogliono usarlo per la documentazione software. Ti fornisce il suo sistema wiki e ti consente di convertire la tua documentazione in vetrine di siti web accattivanti.

Editor di markdown
Poiché la documentazione software è più facile da usare sul web, deve essere creata in un formato appropriato. Ecco perché vengono utilizzati linguaggi di markup basati sul testo. Il più popolare è Markup, che può essere facilmente convertito in HTML e non richiede conoscenze particolari. Markup è utilizzato su GitHub e Reddit, e fondamentalmente ovunque per la documentazione basata sul web.

Ecco quindi alcuni editor Markdown che possono essere utili per creare documenti per il nostro progetto.

Visual Studio Code è un editor di codice open source gratuito sviluppato da Microsoft per Windows, Linux e macOS. Ha molte funzionalità ed estensioni, tra cui quelle per la gestione dei progetti e la collaborazione.

Typora è un editor che fornisce un ambiente di scrittura privo di distrazioni e il rendering in tempo reale della sintassi markdown per una facile creazione e modifica dei file markdown.

iA Writer è un editor di testo minimalista con un’interfaccia semplice e priva di distrazioni e una serie di utili funzioni, tra cui l’evidenziazione della sintassi, il conteggio delle parole e la sincronizzazione con iCloud.

Quiver è un’applicazione per la gestione di appunti e frammenti di codice per dispositivi Mac e iOS. Consente agli utenti di creare e organizzare appunti con una combinazione di testo, frammenti di codice e markdown.

Strumenti specifici della roadmap
È una buona pratica usare strumenti specifici per roadmap, poiché consentono di condividere informazioni rapidamente, aggiornare timeline o temi, aggiungere nuovi punti e modificare l’intera struttura. La maggior parte degli strumenti di roadmap fornisce modelli in modo da poter iniziare a lavorare subito.

ProductPlan offre funzionalità per la creazione di roadmap, timeline, collaborazione, definizione delle priorità e reporting per aiutare le aziende a sviluppare, condividere e gestire le roadmap dei propri prodotti in modo più efficiente ed efficace.

Aha! è una suite di strumenti per l’intero ciclo di vita della gestione del prodotto, dall’idea al lancio, inclusa la roadmap.

Roadmunk offre campi personalizzati, modifica tramite trascinamento della selezione, integrazioni con altri strumenti e funzionalità di collaborazione per consentire ai membri del team di lavorare insieme in tempo reale.

Roadmap Planner di KeepSolid è un altro strumento visivo di pianificazione dei progetti e di collaborazione di gruppo per la creazione di roadmap di progetto, linee temporali e diagrammi di Gantt.

Tutti gli strumenti offrono prove gratuite e piani a pagamento, con differenze nei modelli, nel numero di roadmap e nelle persone con cui è possibile condividerli.

Strumenti per la documentazione UX
Gli strumenti più diffusi per la progettazione dell’esperienza utente sono gli strumenti di prototipazione che aiutano a creare schizzi, mock-up, wireframe e prototipi interattivi.

Sketch è uno strumento di progettazione vettoriale semplice ma potente che ha un’applicazione web e un client desktop Mac. Sketch è ben noto e piuttosto semplice, offrendo sufficienti capacità per la progettazione di interfacce.

piattaforma di Sketch

InVision è uno degli strumenti di prototipazione più popolari. È famoso per le sue funzionalità collaborative e le capacità multipiattaforma, che lo rendono un’ottima opzione per la progettazione di interfacce.

UXPin è uno strumento di progettazione per Mac e Windows che ti consente di creare qualsiasi tipo di blueprint. Puoi anche caricare i tuoi schizzi o wireframe da altri prodotti e crearne un prototipo interattivo.

Adobe XD , dove XD sta per experience design, è un prodotto rivolto agli specialisti UX. Consente ai designer di creare prototipi ad alta fedeltà e condividerli tramite l’app.

Strumenti per la documentazione API
Il processo di creazione della documentazione API è spesso automatizzato. I programmatori o gli scrittori tecnici possono utilizzare i seguenti generatori di documentazione API.

Swagger è una suite di strumenti per la progettazione, la creazione, la documentazione e l’utilizzo di servizi Web RESTful . Offre agli sviluppatori un’interfaccia intuitiva per descrivere la struttura delle loro API, inclusi endpoint, operazioni e modelli, utilizzando la specifica OpenAPI. Ciò consente la generazione automatica di documentazione API interattiva che può essere testata in tempo reale. Gli strumenti di Swagger supportano l’intero ciclo di vita delle API, dalla progettazione e documentazione al test e all’implementazione.

Postman è un altro popolare strumento di sviluppo API utilizzato per la creazione, il test e la gestione delle API. Consente inoltre ai team di creare, condividere e gestire facilmente la documentazione API dettagliata. Questa documentazione è interattiva e consente agli utenti di eseguire richieste API direttamente dai documenti, facilitando test e integrazione più semplici per sviluppatori e stakeholder.

RAML 2 HTML è uno strumento che converte i file RAML (RESTful API Modeling Language) in pagine HTML leggibili dall’uomo. Consente agli sviluppatori di generare documentazione API direttamente dalle loro definizioni RAML.

Strumenti per redattori tecnici
Gli scrittori tecnici professionisti spesso utilizzano software specializzati per creare documentazione tecnica di alta qualità. Tali strumenti sono chiamati sistemi di gestione dei contenuti , o CMS, e consentono di creare, organizzare e gestire più facilmente vari tipi di documentazione. Un CMS può gestire diversi formati di file, importare e archiviare contenuti e consentire a più utenti di contribuire allo sviluppo dei contenuti.

MadCapFlare è un potente software basato su cloud con funzionalità di pubblicazione multicanale, supporto multilingue, ampie risorse di apprendimento e molto altro ancora.

Adobe RoboHelp è un CMS completo che consente di creare contenuti multimediali, gestire facilmente i microcontenuti, collaborare al controllo delle versioni, ecc.

ClickHelp è una piattaforma pluripremiata che offre una facile migrazione da altri programmi, opzioni di autorizzazione flessibili e una serie di funzionalità di reporting.

Esempi e modelli per la documentazione software
Molti degli strumenti descritti nella sezione precedente forniscono una varietà di modelli per la creazione di documentazione tecnica. Tuttavia, se il tuo team sta ancora lottando per trovare un modello qualitativo per un certo tipo di documentazione software, ecco fonti più specializzate da controllare.

Modelli di documentazione generale del progetto
Le seguenti fonti forniscono un’ampia varietà di modelli relativi allo sviluppo software e alla gestione dei progetti.

Atlassian Confluence Templates offre modelli di documentazione di progetto di uso generale, già inclusi nel prodotto.

ReadySET Pro è un’ampia libreria di modelli di documentazione software in HTML che include documenti di pianificazione, architettura, progettazione, requisiti, test e molto altro ancora.

ReadTheDocs è un modello completo creato con la piattaforma ReadTheDocs, che fornisce istruzioni su come scrivere ogni tipo di documento di cui potresti aver bisogno, dall’architettura e dai diagrammi UML ai manuali utente.

TemplateLab contiene migliaia di modelli per vari scopi, compresa la gestione dei progetti.

Modelli di roadmap del prodotto
I modelli scaricabili potrebbero essere più difficili da gestire e su cui collaborare, ma possono comunque farti iniziare rapidamente. Ecco alcune fonti in cui puoi trovare diversi modelli di roadmap:

• Office Timeline
• Template.net
• Slidemodel
• Notion

Modelli di documentazione per la garanzia della qualità
Ecco alcuni modelli relativi al controllo qualità, potremmo controllare qui:

• StrongQA.com
• Template.net
• QATestLab
• Smartsheet

Modelli di documenti di progettazione software
I documenti di progettazione software sono talvolta chiamati anche specifiche di prodotto o tecniche. Sono uno dei pezzi più importanti della documentazione software. Puoi adattare uno di questi modelli alle tue esigenze:

• Sample Templates
• Lucidchart
• Slite
• cs.iit.edu
• Los Alamos National Lab

Esempi di architettura specializzata: AWS, Microsoft Azure e Google Cloud
Oggigiorno, poiché sempre più aziende preferiscono migrare verso il cloud, alcuni noti provider affidabili offrono corsi di formazione ed esempi di architettura per facilitare l’operatività nei loro ambienti.

Amazon , il centro di architettura AWS, fornisce linee guida, framework, strumenti e best practice per l’esecuzione di carichi di lavoro architettonici nel cloud.

Microsoft : questa risorsa suggerisce molti materiali utili sull’architettura di Azure, tra cui scenari di esempio, diagrammi di architettura e altro ancora.

Google : visita la libreria ufficiale di icone di esempio per la creazione di diagrammi architettonici di Google Cloud.

Come scrivere la documentazione software: consigli generali
Esistono diverse pratiche comuni che possono essere applicate a tutti i principali tipi di documentazione di cui abbiamo parlato sopra.

Scriviamo solo la documentazione sufficiente
Dovremmo trovare un equilibrio tra nessuna documentazione e documentazione eccessiva. Una documentazione scadente causa molti errori e riduce l’efficienza in ogni fase dello sviluppo del prodotto software. Allo stesso tempo, non c’è bisogno di fornire un’abbondanza di documentazione e di ripetere le informazioni in diversi documenti. Solo le informazioni più necessarie e rilevanti dovrebbero essere documentate. Trovare il giusto equilibrio comporta anche l’analisi della complessità del progetto prima che inizi lo sviluppo.

Consideriamo il nostro pubblico
Cerca di mantenere la tua documentazione semplice e di facile lettura. Deve essere strutturata in modo logico e facilmente consultabile, quindi includi l’indice. Evita lunghi blocchi di testo quando possibile e usa contenuti visivi poiché è più facile assorbire le informazioni in questo modo per la maggior parte delle persone.

Dobbiamo anche ricordare a chi è destinato il documento. Se è per gli utenti finali, deve sicuramente essere scritto in un linguaggio semplice in modo che i lettori siano in grado di capirlo senza consultare il dizionario tecnico. Se la documentazione è rivolta a stakeholder aziendali, vale anche la pena evitare terminologie complesse e specializzate, gergo tecnico o acronimi poiché il tuo cliente potrebbe non averne familiarità. Tuttavia, se è per il tuo team di specialisti tecnici, assicurati di fornire tutta l’accuratezza e i dettagli di cui hanno bisogno per attenersi al piano di sviluppo e creare il design e le funzionalità necessari.

Utilizzare i collegamenti incrociati
Utilizzare collegamenti incrociati tra documenti correlati o sezioni all’interno di un documento. Ciò è particolarmente utile in set di documentazione complessi in cui le informazioni correlate sono distribuite su più file.

I collegamenti incrociati non solo consentono ai lettori di passare rapidamente alle parti a cui si fa riferimento senza dover effettuare ricerche approfondite, ma contribuiscono anche a evitare ridondanze e a facilitare gli aggiornamenti.

Non ignorare i glossari
La documentazione può essere dedicata all’uso interno o esterno. Nel caso di documenti esterni, è meglio fornire una spiegazione chiara di ogni termine e del suo significato specifico nel progetto. La documentazione dovrebbe comunicare idee in un linguaggio chiaro per impostare una lingua franca tra stakeholder, membri interni e utenti.

Mantere aggiornata la documentazione del software
Una corretta manutenzione è molto importante, poiché i documenti obsoleti o incoerenti perdono automaticamente il loro valore. Se i requisiti cambiano durante lo sviluppo del software, è necessario assicurarsi che vi sia un processo di aggiornamento sistematico della documentazione per includere le modifiche. E, se vengono effettuati aggiornamenti quando il prodotto è già sul mercato, è fondamentale informare i clienti e aggiornare tutta la documentazione utente.

È una buona norma stabilire una sorta di programma di manutenzione e aggiornamento. È possibile farlo a intervalli regolari, ad esempio settimanali o mensili, oppure collegarlo al piano di sviluppo e, ad esempio, aggiornare i documenti dopo ogni rilascio. Le e-mail automatiche o le note di rilascio possono aiutarti a seguire le modifiche apportate dal team di sviluppo.

Possiamo anche usare uno strumento di controllo delle versioni per gestire questo processo in modo più efficiente. Ci consentirà di tenere traccia delle modifiche apportate, conservare le versioni e le bozze precedenti e mantenere tutti allineati.

Collaborare con il team
Il metodo agile si basa su un approccio collaborativo alla creazione di documentazione. Se vuoi raggiungere l’efficienza, intervista programmatori e tester sulle funzionalità del software. Quindi, dopo aver scritto un po’ di documentazione, condividiamola con il nostro team e ricevi feedback. Puoi anche partecipare alle riunioni del team per essere aggiornato o controllare regolarmente la bacheca Kanban. Per ottenere maggiori informazioni, prova a commentare, fare domande e incoraggiare gli altri a condividere i loro pensieri e idee. Ogni membro del team può dare un prezioso contributo ai documenti che produciamo.

Assumi uno scrittore tecnico – Documentazione tecnica del software
Se possibile, vale la pena assumere un dipendente che si occupi della tua documentazione. La persona che generalmente svolge questo lavoro è chiamata technical writer. Un tech writer con un background ingegneristico può raccogliere informazioni dagli sviluppatori senza richiedere a qualcuno di spiegare in dettaglio cosa sta succedendo. Vale anche la pena incorporare un technical writer come membro del team, collocando questa persona nello stesso ufficio per stabilire una stretta collaborazione. Sarà in grado di prendere parte a riunioni e discussioni regolari.

Le migliori pratiche per creare e gestire la documentazione tecnica
Ecco alcuni altri suggerimenti che possono aiutarci a ottimizzare e velocizzare il processo di scrittura e ulteriore gestione dei documenti.

Pensiamo al mezzo più efficiente per trasmettere informazioni. Ad esempio, effettuare registrazioni audio o video può essere un’ottima opzione per l’acquisizione di requisiti, guide utente, ecc.

Collegamento a informazioni supplementari. Inserisci collegamenti agli articoli online o alle pagine informative pertinenti invece di riprodurli nella tua documentazione.

Generiamo diagrammi da codice o database quando possibile. Quando creiamo diagrammi per la documentazione tecnica, invece di crearli da zero con uno strumento di creazione di diagrammi, può essere più efficiente generarli da codice o database quando possibile. Ciò può essere fatto utilizzando vari strumenti e plugin disponibili per i linguaggi di programmazione e i database più diffusi, che possono creare automaticamente diagrammi basati sul codice o sullo schema del database.

Utilizziamo schermate e immagini. È sempre una buona idea utilizzare schermate e altre immagini poiché ti aiuteranno a trovare rapidamente ciò che deve essere aggiornato, così non dovrai leggere l’intero testo.

Manteniamo la documentazione con il codice sorgente. Consideriamo di archiviare la tua documentazione tecnica insieme al codice sorgente, tienili separati. Ciò può aiutare a mantenerlo aggiornato e consentirà a tutti di sapere dove trovarlo.

Personalizziamo l’accesso per evitare modifiche extra. Concediamo autorizzazioni di modifica ai potenziali autori, mentre coloro che hanno accesso di sola visualizzazione possono comunque vedere le informazioni, ma non modificarle.

Fornisci un facile accesso agli autori. Assicurati che gli autori abbiano un accesso rapido e semplice alla documentazione per la revisione e l’aggiornamento. Rimuovi barriere come procedure di autorizzazione e/o approvazione non necessarie.

Ricordiamoci di eseguire il backup. Prendi l’abitudine di creare backup regolari, preferibilmente in più posizioni, come l’archiviazione cloud o un disco rigido esterno. Inoltre, conserva le versioni precedenti e archivia le e-mail sul progetto poiché potresti aver bisogno di recuperarle in futuro. È anche una buona idea avere un programma di backup per assicurarti di avere sempre accesso alla versione più recente della tua documentazione. Assicuriamoci di testare periodicamente i tuoi backup per assicurarti che funzionino correttamente e possano essere utilizzati in caso di emergenza.

Usiamo i tag per semplificare la ricerca. Prendi in considerazione l’utilizzo di tag per categorizzare ed etichettare diverse sezioni e argomenti all’interno della tua documentazione. Quando crei tag, pensa alle parole chiave o agli argomenti più pertinenti per ogni sezione e assicurati che siano coerenti in tutta la tua documentazione. Inoltre, prendi in considerazione l’utilizzo di tag gerarchici per perfezionare e organizzare ulteriormente il tuo contenuto, rendendolo più facile da navigare e cercare.

Esploriamo possibili metodi di comunicazione. Se la documentazione è un modo per condividere la conoscenza, pensa ad altri mezzi di comunicazione o scopri perché i membri del team non ne parlano e basta. Può essere utile per il lavoro di squadra complessivo e ridurre la quantità di documentazione necessaria.

La metodologia Agile incoraggia i team di ingegneria a concentrarsi sempre sulla fornitura di valore ai propri clienti. Questo principio chiave deve essere preso in considerazione anche nel processo di produzione della documentazione software. Dovrebbe essere fornita una buona documentazione software, che si tratti di un documento di specifiche software per programmatori e tester o di manuali software per gli utenti finali. La documentazione software completa è specifica, concisa e pertinente.

(fonte)

Innovaformazione, scuola informatica specialistica promuove la cultura IT fra aziende e privati. Trovate l’offerta formativa sul nostro sito QUI.

INFO: info@innovaformazione.net – Tel. 3471012275 (Dario Carrassi)