La documentazione è una parte essenziale del ciclo di sviluppo del software. Spiega come utilizzare il software e può includere guide per l'utente, riferimenti API, istruzioni di installazione e note di rilascio.
L'automazione della documentazione è l'ultima tendenza poiché può aiutare a risparmiare tempo, ridurre gli errori e garantire la coerenza. Mantenere la documentazione aggiornata e accessibile a tutte le parti interessate facilita la collaborazione e il miglioramento continuo.
Docs as code è un approccio all'automazione della documentazione che tratta la documentazione tecnica come codice.
Cos'è Docs come codice?
Docs as code è una filosofia di sviluppo software che vede la documentazione tecnica come una forma di codice. Suggerisce di trattare la documentazione con lo stesso rigore e lo stesso processo del codice software.
L'idea alla base di docs as code è quella di trattare la documentazione come un artefatto di prima classe del processo di sviluppo, integrandola con il ciclo di vita del software. Ciò significa trattare la documentazione come parte integrante della base di codice. Significa applicare ad esso lo stesso controllo della versione, l'integrazione continua e i processi di test che fai al codice stesso.
In un tipico documento come impostazione del codice, scrivi la documentazione in file di testo normale, di solito in un linguaggio di markup leggero come Markdown, HTML o testo ristrutturato. Quindi lo memorizzi nello stesso repository del codice sorgente. Ciò semplifica la gestione e il monitoraggio delle modifiche sia al software che alla documentazione. Aiuta inoltre a garantire che la documentazione sia aggiornata con l'ultima versione del codice.
Perché dovresti usare Docs come codice
Prima dei documenti come codice, la documentazione veniva spesso trattata come separata dal codice, creata con strumenti e processi diversi. Questo approccio più flessibile portava spesso a documentazione obsoleta e incoerenze con il codice. Puoi sfruttare diversi vantaggi adottando i documenti come approccio al codice.
Collaborazione migliorata
I documenti come codice consentono la collaborazione tra sviluppatori, redattori tecnici e altre parti interessate nel processo di sviluppo. Poiché il repository di codice ospita la documentazione, è facile per le diverse parti contribuire e apportare modifiche. Ciò aiuta a garantire che la documentazione sia accurata, aggiornata e completa.
Un approccio collaborativo alla documentazione aiuta a garantire che includa tutte le informazioni pertinenti e che rifletta accuratamente il sistema software come interpretato da tutte le parti.
Automazione dei processi e accessibilità
Un altro vantaggio dei documenti come codice è che consente agli strumenti automatizzati di generare e pubblicare documentazione. Un sistema di compilazione può generare automaticamente versioni HTML o PDF della documentazione da file di testo normale per la pubblicazione su un sito Web o un portale di documentazione interno. Ciò rende la documentazione accessibile a più parti interessate.
Automatizzando il processo di generazione e pubblicazione della documentazione, docs as code aiuta a ridurre il tempo e lo sforzo necessari per mantenere e pubblicare la documentazione. Consente ai team di sviluppo di concentrarsi sul miglioramento del software.
Controllo della versione
L'archiviazione della documentazione nello stesso repository di codice del software semplifica la gestione e il monitoraggio delle modifiche apportate a entrambi.
Puoi usare sistemi di controllo della versione come Git per tenere traccia delle modifiche alla documentazione e ripristinare le versioni precedenti, se necessario. Questo aiuta a garantire che la documentazione sia accurata e aggiornata e puoi tracciare e controllare le modifiche.
I documenti tipici come flusso di lavoro del codice
I documenti tipici come flusso di lavoro del codice comprendono la scrittura, il controllo della versione, la creazione e l'hosting:
Il processo di scrittura
Il processo di scrittura è la prima fase di un tipico flusso di lavoro di documenti come codice. Maggior parte scrittori tecnici e gli ingegneri della documentazione usano semplici MarkDown, AsciiDoc o HTML. Scrivono la documentazione utilizzando strumenti come GitBook e Redocly che assicurano un processo fluido.
Controllo della versione per la documentazione
La documentazione si evolve con l'evoluzione del codice. Avrai bisogno di un sofisticato sistema di controllo della versione come Git, Plastic SCM o Subversion per tenere traccia delle modifiche alla documentazione per facilitare la collaborazione e il monitoraggio della versione.
Il processo di compilazione della documentazione
Il processo di compilazione prevede l'elaborazione e la compilazione della documentazione nei relativi formati di consegna. Questi potrebbero essere HTML, PDF, EPUB o altri. Il processo di documentazione è solitamente reso più semplice utilizzando generatori di siti statici come Hugo e Jekyll.
Ospitare e distribuire la documentazione
Il processo di hosting o distribuzione è solitamente l'ultimo passaggio dei documenti come processo di codifica. Questo processo garantisce che la documentazione sia consegnata all'utente finale e disponibile a tutte le parti interessate. Puoi utilizzare le pagine GitHub o GitLab o un portale personalizzato per distribuire la tua documentazione sul web.
Puoi automatizzare la documentazione Go e Java utilizzando GoDoc e JavaDoc
La filosofia dei documenti come codice sta rivoluzionando la scrittura e la gestione della documentazione tecnica.
Molti linguaggi di programmazione, tra cui Go e Java, forniscono strumenti per automatizzare la documentazione utilizzando i commenti del codice. Go fornisce lo strumento Godoc e Java fornisce JavaDoc.