Passare dalla documentazione Sphinx alla documentazione MkDocs: cosa ho guadagnato e cosa ho perso? | di Kay Jan Wong | Febbraio 2024 | Intelligenza-Artificiale

Guida su come eseguire questo passaggio e un confronto tra loro

“Un progetto è valido tanto quanto la sua documentazione” – una citazione dalla mia precedente serie di articoli in 3 parti che sottolinea l’importanza della documentazione. Da allora ho appreso che esistono diversi tipi di documentazione, i più comuni sono:

1. Documentazione tecnica: Descrive gli aspetti tecnici del funzionamento interno del progetto, può trattarsi di documentazione di processo o documentazione di prodotto
2. Documentazione aziendale: descrivere quali problemi aziendali risolve o quali obiettivi aziendali vengono raggiunti

Esiste un tipo di documentazione che è una via di mezzo, si tratta di manuali, guide e tutorial. Questo è particolarmente importante se lo desideri utenti tecnici per lavorare o utilizzare il tuo progetto, o utenti aziendali per comprendere il tuo progetto e ottenere buy-in.

Man mano che la documentazione diventa più complessa con più contenuti, può essere difficile visualizzarla in un file formato intuitivo e leggibile. Ad esempio, i tutorial non dovrebbero essere incorporati nella documentazione tecnica e, idealmente, tra di essi dovrebbe esserci una scheda o una sezione di navigazione separata.

Ciò mi ha spinto a esplorare più temi Sfinge per rendere la mia documentazione più bella e per essere in grado di gestire più informazioni. Alla fine ne sono stato attratto Materiale Sfinge E Sfinge-Immateriale temi che implementano il tema Material di MkDocs. Dopo molte modifiche e senza ancora ottenere i risultati desiderati, sono passato a MkDocs e finalmente ho capito l’hype su MkDocs.

Avendo provato vari metodi e temi di documentazione, proverò a confrontarli, concentrandomi su caratteristiche acquisite e perse dal passaggio da Sphinx a MkDocs. Infine, questo articolo si concluderà con importanti impostazioni di MkDocs da incorporare per una documentazione più ottimale!

Nota: Se interessati, questo è il collegamento alla mia documentazione realizzata con il tema Sphinx-Material, e questo è il collegamento alla stessa documentazione realizzata con MkDocs 🙂