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:
- Documentazione tecnica: Descrive gli aspetti tecnici del funzionamento interno del progetto, può trattarsi di documentazione di processo o documentazione di prodotto
- 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 🙂
Fonte: towardsdatascience.com
