Introduzione

Ci sono diversi modi di accedere alle informazioni :

  1. (crono)logico, come leggere pagina per pagina, riga per riga, fino a raggiungere la fine della pubblicazione,
  2. tematico, come andare all’indice e saltare direttamente alla parte che ti interessa, a condizione che il contenuto sia suddiviso in unità di contenuto significative,
  3. trasversale, come seguire una sezione «articoli correlati» basata sulla somiglianza dei contenuti (definita manualmente, con tag e parole chiave, oppure appresa tramite analisi tematica con IA), o riferimenti incrociati espliciti. Per esempio, la maggior parte dei siti web ha archivi che elencano tutte le pagine con un certo tag/parola chiave, i libri hanno i glossari.
  4. basato su suggerimenti, come presentare una bibliografia di pubblicazioni più approfondite o una sezione «maggiori informazioni» alla fine del contenuto, o anticipare contenuti successivi,
  5. basato sulle fonti, seguendo i riferimenti (tipicamente note a piè di pagina o note a margine) alle pubblicazioni da cui l’informazione è estratta, principalmente a scopo di verifica,
  6. reperimento delle informazioni, ovvero il motore di ricerca.

Devi supportarli tutti contemporaneamente perché sono complementari e il migliore in un dato contesto dipende dalle conoscenze iniziali e dalle esigenze del lettore. Nessuno di questi modi è superiore agli altri. Ciò significa che c’è una discreta quantità di «keyword stuffing» da fare nella tua scrittura, per garantire che l’analisi dei contenuti basata sulle parole chiave e il reperimento delle informazioni tramite parole chiave funzionino come previsto.

Un manuale/documentazione non è un corso, ma attenersi a un’arida lista di funzioni/controlli dell’interfaccia e alla loro definizione è… troppo arido. Devi creare collegamenti tra i contenuti (che non sono semplicemente link HTML). In Ansel, i flussi di lavoro partono da un obiettivo e srotolano gli strumenti per raggiungerlo. La documentazione parte dagli strumenti e presenta come e dove possono essere usati. Ma questi sono i due estremi dello spettro, e la realtà è sempre un po’ nel mezzo.

Il sapere è comunque un grafo di rete . Devi solo fare attenzione ai collegamenti tra i nodi. Sono importanti almeno quanto il contenuto.

Implementazione pratica in Ansel

Ansel utilizza Hugo  come CMS, sia per la documentazione che per il resto del sito web. L’implementazione pratica dei principi enunciati sopra dovrà fare i conti con le funzionalità di base di Hugo.

Accesso (crono)logico e tematico

I contenuti di Hugo sono organizzati in sezioni  che sono essenzialmente sottocartelle della cartella principale /content. Le sottocartelle possono essere annidate all’infinito. Il tema del sito web presenta la vista ad albero di tutte le sezioni nella barra laterale sinistra, su schermi ampi (desktop). I livelli superiori delle sezioni e sottosezioni possono essere espansi/compressi su richiesta dell’utente. Questa vista ad albero fornisce l’indice di primo livello che funge da accesso tematico.

All’interno delle sezioni, l’ordine relativo delle pagine può essere definito manualmente usando il parametro weight  nelle intestazioni Markdown, in questo modo :

1---
2title: Documenting Ansel
3date: 2025-10-13
4weight: 9
5---
6
7My content here

Il parametro weight è opzionale. Se non usato, gli elenchi delle pagine useranno tipicamente la date per ordinare i contenuti, ma potrebbero anche usare l’ordinamento alfabetico sul titolo della pagina. Questo ordinamento fornisce l’accesso (crono)logico.

All’interno delle pagine, se ci sono più di due sezioni nel contenuto (definite da titoli di secondo livello, ad esempio <h2> in HTML o ## in Markdown), un indice interno verrà aggiunto automaticamente da Hugo nella barra laterale destra, su schermi ampi (desktop).

Accesso trasversale

I tag possono essere definiti sul sito web usando il parametro tags nell’intestazione Markdown, in questo modo :

1---
2title: This page title
3date: 2022-12-04
4tags:
5    - color science
6    - pipeline
7---
8
9Your content

I tag sono opzionali e vengono visualizzati come link cliccabili in vari punti del tema del sito web. Cliccando su un tag si apre il suo archivio, che elenca tutte le pagine aventi quel tag. Questo fornisce l’accesso trasversale.

Gli autori sono inoltre incoraggiati ad aggiungere collegamenti incrociati nei loro contenuti, da pagine del sito web ad altre pagine del sito web, per promuovere l’accesso trasversale. I concetti che hanno una voce sul sito web dovrebbero essere trasformati in link alla pagina che descrive ciascun concetto.

Basato su suggerimenti

Gli autori sono liberi di aggiungere una sezione Bibliografia o Maggiori informazioni alla fine delle loro pagine, con un elenco di pubblicazioni e link. Queste pubblicazioni possono essere interne o esterne al progetto Ansel. Possono essere periferiche rispetto all’argomento trattato nel contenuto.

È anche possibile concludere le pagine con un’apertura sul prossimo passo logico, quando si scrive di flussi di lavoro o moduli.

Basato sulle fonti

Hugo supporta il Markdown esteso, che supporta le note a piè di pagina . Queste sono consigliate per fare riferimento alle fonti, in questo modo :

1The typical observer has Just Noticeable Difference (Delta E) of 2.3[^1]
2
3[^1]: Some Author, Some Publisher, _A real-world, large-sampled, study of vision parameters for white, rich, educated, American students of the Rochester Institute of Technology_, (some year). [URL](https://doi.org/xxxxx)

Ansel non ha adottato alcun formato accademico particolare per le citazioni delle fonti in questo momento, sebbene lo stile di citazione IEEE  sembri il più adatto all’approccio con note a piè di pagina con indice numerico.

Assicurati di includere il DOI  della pubblicazione, o almeno qualche URL a lungo termine dal quale possa essere recuperata ora e in futuro.

Reperimento delle informazioni

Per ora, Chantal  si occupa di quella parte. L’indice web viene aggiornato manualmente e periodicamente.

Linee guida

Scrivere, anche in ambito tecnico, è un’arte difficile da ridurre a un insieme di linee guida definite o buone pratiche, perché ciò varia a seconda del contesto. Devi fare attenzione a non essere più realista del re. Una buona regola pratica è scrivere per risolvere problemi, il che significa iniziare chiedendoti perché e da dove il lettore è approdato sulla pagina che stai scrivendo :

  1. che tipo di conoscenze si suppone/presume che il lettore abbia già ?
    • il lettore dovrebbe idealmente essere consapevole di questi prerequisiti, quindi magari inizia con un elenco di link,
    • tutto ciò che non è in questo elenco dovrebbe essere definito e spiegato nella tua pagina,
  2. che tipo di compito il lettore sta cercando di completare che lo ha portato a questa pagina ?
    • vuole un rapido promemoria, o un how-to dettagliato, o un fondamento teorico ? Potresti dover sceglierne uno arbitrariamente.
    • questo deciderà quali suggerimenti potresti aggiungere nel testo per migliorare la rete di conoscenze,
    • questo dovrebbe probabilmente orientare l’intera prospettiva del tuo contenuto e la sua lunghezza/profondità.

Un buon modo per valutare la qualità della documentazione è osservare le domande frequenti (o gli argomenti meno compresi) sui forum. Se l’argomento è già trattato ma le domande continuano a sorgere, può essere perché la documentazione non è chiara o le pagine pertinenti sono sepolte nella rete e non abbastanza rintracciabili.

Translated from English by : Claude. In case of conflict, inconsistency or error, the English version shall prevail.