La maggior parte degli strumenti di documentazione esporta HTML statico. MkDocs, Sphinx, Docusaurus, Hugo, un riferimento API generato: il risultato è una cartella autonoma, progettata per funzionare senza connessione. È esattamente ciò che serve in aereo, nel seminterrato di un datacenter o da un cliente il cui wifi rifiuta il tuo portatile.
Resta da aprirla sul tablet che hai portato.
Perché il PDF non è la risposta
Il riflesso è esportare la documentazione in PDF. Funziona, e per un documento breve è spesso la scelta giusta. Ma una documentazione tecnica perde molto nella conversione.
- La navigazione laterale sparisce, sostituita da uno scorrimento di diverse centinaia di pagine.
- I link tra sezioni diventano nel migliore dei casi rimandi di pagina, nel peggiore testo morto.
- L'evidenziazione della sintassi e i blocchi di codice comprimibili non sopravvivono sempre.
- Ogni aggiornamento impone di rifare l'esportazione.
Eppure l'esportazione HTML esiste già, e contiene tutto questo.
Tenere la documentazione com'è stata generata
Pagira apre la cartella di esportazione come farebbe un browser: la barra laterale, i link tra le pagine, l'evidenziazione del codice. Consulti la documentazione, non una fotografia della documentazione.
- Copia la cartella di esportazione in File o in iCloud Drive.
- Aprila con Pagira.
- Naviga come sul sito: la barra degli strumenti dà indietro, avanti e ricarica.
iCloud Drive e la questione dell'offline
Una documentazione generata pesa spesso diverse centinaia di megabyte, immagini e font compresi. Messa su iCloud Drive, si scarica mentre leggi, senza attesa prima che compaia la prima pagina.
Prima di una trasferta, scarica una copia offline permanente. Il download è riprendibile, quindi un'interruzione non ricomincia da capo, e un banner chiarisce cosa resta consultabile senza rete. Vedi streaming da iCloud Drive o copia offline.
Preparare le pagine che ti serviranno
C'è l'offline subito e l'offline preparato. Se sai già quali documenti consulterai, scaricali per l'offline prima di partire, e aggiungi i più utili ai preferiti: ti aspettano nella Home, e ognuno si riapre alla pagina in cui l'avevi lasciato. Vedi i preferiti.
Il caso delle documentazioni miste
Una documentazione aziendale mescola quasi sempre pagine HTML e PDF: una specifica, uno schema di architettura, un allegato contrattuale. Entrambi si aprono nella stessa app, e un link da una pagina a un PDF si apre sul posto.
Domande frequenti
E una documentazione da diversi gigabyte?
Lo streaming da iCloud evita di dover scaricare tutto in una volta. Per l'offline completo, il limite è lo spazio disponibile sul dispositivo.
La mia documentazione è riservata
Non viene inviato nulla. Tutto è reso in locale, che è proprio l'argomento contro un servizio online di visualizzazione documenti.
Posso consultarla anche su iPhone?
Sì, una sola app copre entrambi. Con iCloud, la pagina a cui sei arrivato e i tuoi preferiti ti seguono da un dispositivo all'altro, per i documenti che si trovano in iCloud Drive.
Come la apro da un altro strumento?
Dal menu di condivisione, con Apri con Pagira, da File o da qualsiasi app. Vedi aprire da qualsiasi punto.
