Sistema di documentazione

Manifesto
Configurazione Obsidian

Architettura di Sistema¶

L'idea generale

flowchart LR
A(Contenuti) --> B(Controllo versione)
C(Software di editing) --> A
A --> D(Rendere accessibile online)

Nel dettaglio:

flowchart LR
A[Obsidian] <--> B{File}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Tema: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D

Componenti nel dettaglio¶

1. Markdown¶

Vantaggi:

• È facile da imparare e utilizzare, il che mi permette di concentrarmi sul contenuto.
• È indipendente dalla piattaforma, quindi posso continuare il mio lavoro su qualsiasi dispositivo.
• È ideale per il controllo versione, il che mi consente di tracciare e gestire le modifiche.
• È a prova di futuro e non proprietario, il che mi dà la certezza che il mio lavoro rimarrà accessibile a lungo termine.

Markdown

2. Obsidian¶

• Posso salvare i miei dati localmente e modificarli offline, il che mi dà flessibilità e controllo.
• Posso collegare facilmente i file tra loro, il che mi aiuta a organizzare informazioni complesse.
• Posso taggare i file e gestirli facilmente, il che mi offre una dimensione aggiuntiva di organizzazione.
• Posso visualizzare i miei dati graficamente, il che mi aiuta a riconoscere schemi e relazioni.
• Posso estendere la funzionalità di Obsidian tramite plugin, il che mi permette di adattare lo strumento alle mie esigenze specifiche.

3. Git e Github¶

Vantaggi:

• Controllo versione: Ogni modifica viene documentata e può essere tracciata in qualsiasi momento, il che mi aiuta a evitare errori e a mantenere una visione d'insieme.
• Collaborazione: Più persone possono lavorare contemporaneamente alla documentazione, il che mi dà la possibilità di integrare feedback e contributi da altri.
• Backup: La mia documentazione è sicura e viene regolarmente sottoposta a backup, il che mi dà la certezza che il mio lavoro non andrà perso.

4. Github Desktop¶

Vantaggi:

• Facilità d'uso, il che mi semplifica l'utilizzo di Git.
• Non sono necessarie conoscenze della riga di comando, il che mi fa risparmiare tempo e fatica.
• Semplifica il mio flusso di lavoro, il che mi permette di concentrarmi sulla creazione di contenuti.

5. MkDocs¶

Vantaggi:

• Creazione di siti web semplice, il che mi permette di pubblicare la mia documentazione in modo rapido e semplice.
• Aggiornamento rapido, il che mi permette di vedere le modifiche in tempo reale.
• Layout coerente, il che garantisce una presentazione professionale e uniforme della mia documentazione.
• Anteprima offline, il che mi permette di controllare la mia documentazione prima di pubblicarla.

6. Github Pages¶

Vantaggi:

• Hosting gratuito, il che mi permette di pubblicare la mia documentazione senza costi aggiuntivi.
• Pubblicazione semplice, il che mi solleva dall'implementazione tecnica della pubblicazione.
• Affidabile, il che mi dà la certezza che la mia documentazione sarà sempre disponibile.

7. MkDocs-Material¶

Vantaggi:

• Design moderno, il che fa apparire la mia documentazione professionale e attuale.
• Personalizzabile, il che mi permette di adattare il layout alle mie esigenze specifiche.
• Facile da usare, il che mi semplifica l'utilizzo della documentazione.

8. MkDocs-Publisher¶

Vantaggi:

• Integrazione semplificata con Obsidian: Adattamento automatico della sintassi Markdown di Obsidian (Callouts, Wikilinks, ecc.).
• Metadati estesi: Integrazione di tag e categorie dal frontmatter di Obsidian.

Flusso di lavoro¶

1. Creo e modifico file Markdown con un editor di testo (opzionalmente Obsidian).
2. Salvo i file Markdown localmente.
3. Trasferisco le mie modifiche al repository Git con Github Desktop.
4. Faccio creare automaticamente il sito web con MkDocs.
5. Pubblico il sito web con Github Pages.

File system¶

/docs/     (Qui si trovano i miei file Markdown)
/site/     (Qui viene generato il sito web)
license    (Informazioni sulla licenza)
mkdocs.yml (File di configurazione per MkDocs)
readme.md  (File per la descrizione del repository)

Alternative per la creazione di contenuti¶

1. Wordpress: I contenuti possono essere creati in Wordpress come pagina.
2. File di testo, file Word: I contenuti possono essere creati come file di testo, file Word (o in altri formati tipici).

In questi casi, posso quindi integrare i contenuti nel sistema.