Per la documentazione del codice è assolutamente necessario utilizzare un sistema come doxygen o equivalenti in modo che la maggior parte delle informzioni vengano aggiornate automaticamente quando si modifica il codice.
Per una documentazione funzionale più ad alto livello, il mio parere è che la cosa migliore al momento sia utilizzare markdown ( + mermaid) con i file md versionati insieme al codice. Per quanto possibile anche qui bisognerebbe generare in automatico almeno parte delle informazioni che sono generabili.
Ad esempio se nel tuo software hai una state machine con vari stati e transizioni ti fai dei tool che permettano la generazione dei file md+mermaid per la visualizzazione della state machine.
Esempio 2: Hai vari parametri con nome/tipo/descrizione che vengono caricati da un file json nel tuo applicativo? Nel codice dovrai avere una lista di parametri con questi dati dalla quale poi puoi generare anche la documentazione. Da notare che questo è lo stesso concetto che si usa in architetture model-view. Il tuo modello dei parametri contiene le informazioni per generare le view. Una view è l'interfaccia dell'applicazione, un'altra è la documentazione stessa.
Questo ti garantisce che la documentazione sia sempre in linea con il codice stesso e richiede disciplina anche sulla struttura stessa del software.
Perché questo funzioni come si deve bisogna automatizzare i processi di generazione della documentazione ad esempio attraverso i tool di automazione (e.g. github actions) che prendono i tuoi file MD, generano documentazione aggiuntiva, integrano tutto, convertono l'md in un bel pdf, e te lo fanno scaricare.. oppure ad esempio convertono tutto in html e pubblicano direttamente su github pages. Potenzialmente questo passaggio non è nemmeno necessario se il file md è sul repo stesso dato che piattaforme come github/gitlab etc.. permettono di visualizzarli direttamente via web. Vedi ad esempio https://github.com/mermaid-js/mermaid/blob/develop/README.md
Ovviamente questi sono solo esempi su come approciarsi alla documentazione in maniera più strutturata. Il lavoro grosso della documentazione non è farla, è tenerla aggiornata; non c'è nulla di peggio di documentazione obsoleta e sbagliata.