Show More
Menu
Image
Hi there! I am Federico Trotta

Technical WriterFreelance

Docs-as-code: Perché Trattare la Documentazione Come il Codice

Marzo 3, 2024
By Federico
0 Comments
Post Image

Quando si deve iniziare una strategia di implementazione della documentazione per il software, una delle metodologie che si possono scegliere è la cosiddetta filosofia “docs-as-code” che non significa nient’altro che trattare la documentazione come fosse codice.

In questo articolo vediamo quali sono le caratteristiche della metodologia doc-as-code e perché utilizzarla.

Caratteristiche della metodologia docs-as-code

Applicare la metodologia docs-as-code e trattare la documentazione come il codice significa utilizzare metodi tipici dello sviluppo come:

  • Uso di Git. In particolare, GitHub per:
    • Versionamento della documentazione.
    • Revisione collaborativa tramite Pull Requests e relative conversazioni.
    • Deploy tramite l’uso di automazioni.
    • Integrazione dei test sulla documentazione.
  • Uso del Markdown.
  • Massima personalizzazione.
  • Deploy di pagine statiche tramite servizi come GitHub pages o Jekyll.
  • Possibilità di fare interagire gli utenti con la documentazione, aprendo Pull Requests al fine di migliorare la qualità della documentazione.

Quando implementare la metodologia docs-as-code per la tua documentazione

Quando si inizia un progetto documentale da zero, la parte di progettazione è molto importante.

In generale, è sempre buona norma poter creare la documentazione seguendo la metodologia docs-as-code, ma è opportuno prendere in considerazione l’ambiente in cui si va ad implementarla ed i relativi stakeholders.

Non tutti gli stakeholders che interagiscono con la documentazione, infatti, hanno le stesse conoscenze e competenze dei developers. A volte, chi revisiona la documentazione può essere una persona che lavora nel marketing piuttosto che un project manager. Queste figure possono non avere confidenza con l’uso di Git e di relativi strumenti.

Quindi, in generale, questa metodologia può essere implementata quando si lavora in ambienti aziendali in cui gli stakeholders:

  • Sono tutti developers.
  • Non sono tutti developers, ma hanno familiarità con le metodologie tipiche dello sviluppo.

Naturalmente, la scelta dipende anche dal tipo di azienda. In generale, è facile che in una start up tutti gli stakeholders abbiano familiarità con le metodologie tipiche dello sviluppo. Meno, in una azienda di grandi dimensioni.

In ogni caso, quando si fa la progettazione della documentazione, questa la prima cosa che viene decisa e lo si fa stabilendo chi interagirà con la documentazione, compresi revisori.

Perché implementare questa metodologia di gestione della documentazione

Implementare questa metodologia di gestione della documentazione garantisce:

  • La massima flessibilità nell’implementazione dei template disponibili, così da avere un front-end praticamente su misura.
  • Rapidità di esecuzione e messa in produzione, in quanto si tratta di siti statici.
  • Possibilità di testare funzionalmente la documentazione e di visualizzarla in un ambiente di staging, così da evitare errori prima della fase di deploy in produzione.
  • Un ambiente altamente collaborativo.

Conclusioni

Quando possibile, scegliere di sviluppare la documentazione seguendo la metodologia doc-as-code è sicuramente preferibile.

Per poterlo fare, però, gli stakeholders implicati nella gestione della documentazione devono avere familiarità con le metodologie tipiche dello sviluppo.

In fase di progettazione, una volta definiti gli stakeholders, si stabilisce se questa metodologia sia applicabile alla tua azienda o meno.


Ciao, io sono Federico e sono un Technical Writer freelance:

Federico Trotta

Vuoi far partire un progetto documentale per il tuo prodotto digitale, collaborando con me? Contattami!

Vuoi saperne di più su come lavoro? Puoi partire dai miei case studies e dal mio portfolio.

Federico Trotta

Technical Writer: I document digital products and write articles about AI & Python programming.

Leave a reply