Heathrow chiuso: Sospensione dei voli dovrebbe continuare nei prossimi giorni, afferma il manager dell’aeroporto di Londra
Dal sito della BBC
British Airways ha stimato che l’85% dei suoi voli programmati sarebbe stato effettuato sabato, ma con ritardi su tutti i voli. Alle 7:00 GMT, la maggior parte delle partenze era avvenuta come previsto, ma, degli arrivi, nove dei primi venti voli programmati per atterrare sono stati cancellati.
Nuovo Aggiornamento per Minecraft Aggiunge Templi Subacquei
Ci è stato un errore nel mio aggiornamento
api_key = "a quick brown fox"
fetch("https://api.example.com/data", headers: { 'Authorization' => api_key })
Per favore aiutatemi a risolverlo.
Documentazione come codice
Create bozze con formattazione avanzata e lavorate alla documentazione come fate con il codice software. Questo offre diversi vantaggi:
- risparmio di tempo sulla formattazione e conversione
- generazione automatica della documentazione online
- modalità offline (grazie alla cache del browser), particolarmente preziosa:
- nelle reti chiuse del cliente
- in aree senza internet.
“I clienti hanno molto apprezzato questa possibilità” - vorrei scrivere, ma in Russia siamo parchi nel dare feedback positivo sulle cose utili. Per me, è sufficiente la valutazione di un cliente che ha utilizzato una pagina memorizzata nella cache per un anno e cercava di capire i ragazzi del progetto che menzionavano nuovi schemi e testo che il cliente non aveva visto. E quando la pagina è stata aperta da un altro computer, hanno capito che senza internet non si apriva per nessuno tranne che per loro stessi. Quindi il tempo dedicato alla documentazione non è stato sprecato.
Problema: Documentare in condizioni di multitasking
La fretta di svolgere le attività quotidiane e i frequenti cambi dovuti a emergenze non lasciavano tempo per la documentazione. La questione dell’ottimizzazione della sua scrittura veniva sollevata tra continui passaggi tra:
- pipeline CI/CD
- monitoraggio
- automazione
- R&D
- supporto delle attività di cui sopra
- supporto clienti
- e un attento tracciamento del tempo
Non c’era possibilità di concentrarsi sulla documentazione di qualità. E non so come fare le cose in modo approssimativo.
Cosa era necessario:
- registrare le azioni
- integrare le note con immagini, link ed etichette temporali
- evitare la mescolanza di argomenti diversi in una singola bozza
- garantire la possibilità di iniziare a lavorare su un computer e continuare su un altro, inclusi i dispositivi mobili
- salvare automaticamente le bozze in modo che siano accessibili da qualsiasi dispositivo
- ripristinare facilmente il flusso di lavoro in futuro
- avere la possibilità di condividere le bozze in ogni fase del lavoro.
Inizialmente, l’idea era quella di trasformare una bozza in un documento di lavoro completo e pubblicarlo come parte della documentazione del progetto senza legarsi alle fasi del cronogramma. In definitiva, l’approccio trovato ha permesso di andare oltre l’uso locale ed è diventato de facto parte dell’infrastruttura complessiva delle conoscenze e spesso i team hanno iniziato a utilizzarlo come standard.
Obiettivo: Documentazione come codice
Scrivere bozze con formattazione avanzata e lavorare alla documentazione come si fa con il codice software. Questo offre diversi vantaggi:
- risparmio di tempo sulla formattazione e conversione
- generazione automatica della documentazione online
- modalità offline (grazie alla cache del browser), particolarmente preziosa:
- nelle reti chiuse del cliente
- in aree senza internet.
“I clienti hanno molto apprezzato questa possibilità” - vorrei scrivere, ma in Russia siamo parchi nel dare feedback positivo sulle cose utili. Per me, è sufficiente la valutazione di un cliente che ha utilizzato una pagina memorizzata nella cache per un anno e cercava di capire i ragazzi del progetto che menzionavano nuovi schemi e testo che il cliente non aveva visto. E quando la pagina è stata aperta da un altro computer, hanno capito che senza internet non si apriva per nessuno tranne che per loro stessi. Quindi il tempo dedicato alla documentazione non è stato sprecato.
Stack tecnologico scelto
La base è il formato Markdown, perché:
- supportato in GitLab, YouTrack, alcuni messenger
- correttamente riconosciuto da tutti i moderni LLM
- evita problemi con le versioni di Word, immagini “andate via” e formati incompatibili.
Dalla bozza si può ottenere immediatamente:
- versione online
- un rigoroso e bello PDF nello stesso stile della versione online.
Pratica attuale di documentazione
Oggi la documentazione:
- È scritta in formato Markdown
- È memorizzata in GitLab:
- accessibile a tutti i dipendenti tramite modello basato sui ruoli
- supporta la modifica da parte di più utenti
- Viene raccolta automaticamente nella versione online:
- viene utilizzato un contenitore Docsify
- l’aggiornamento avviene ogni minuto
- i siti vengono pubblicati su Internet tramite DNS (con un nome a 3 o 4 livelli per ciascun progetto)
- Viene esportata in PDF con uno stile uniforme (basato su Vue.js), identico per il sito e il file
- I diagrammi sono creati in due formati:
- Draw.io (outline, per schemi complessi)
- Mermaid (inline, direttamente in Markdown)
- Esportazione dei diagrammi:
- in SVG (formato principale)
- a volte in PNG (per piattaforme incompatibili)
- includendo il codice sorgente del diagramma all’interno del file.
Modello a tre livelli di documentazione - e la sua semplificazione
Inizialmente, ho considerato tre livelli di documentazione:
- Bozze - note personali, in rapida evoluzione.
- Documentazione frequentemente modificata - materiali di lavoro collaborativi.
- Documentazione statica - versioni finali e verificate.
Tuttavia, ho deciso di:
- abbandonare l’anonimato e l’isolamento delle bozze,
- unire il primo e il secondo livello in Wiki-bozze comuni basate su Discourse
- lasciare la documentazione statica in GitLab + Docsify.
Anche se non esiste una sincronizzazione automatica tra il secondo e il terzo livello, ritengo che questo approccio sia valido: semplifica il flusso di conoscenze, riduce la barriera all’ingresso per i colleghi e accelera il passaggio da un’idea alla pubblicazione.
Strumenti e formati
||||\n| — | — | — |\n|Testo|Markdown (.md)|Formato di scrittura principale|\n|Archiviazione|GitLab|Versionamento, revisione, accesso basato sui ruoli|\n|Pubblicazione online|Docsify (in un contenitore Docker)|Assemblaggio automatico del sito da Git|\n|Bozze e discussioni|Discourse|Elaborazione collettiva di idee|\n|Diagrammi (integrati)|Mermaid|Diagrammi a blocchi, sequenze direttamente in Markdown|\n|Diagrammi (esterni)|Draw.io (.drawio → .svg)|Schemi architettonici complessi|\n|Esportazione in PDF|Docsify + stile Vue uniforme|Per l’accesso offline e la consegna ai clienti|\n
Cosa c’è di più
Ci sono ancora cose su cui lavorare nel sistema:
- Sincronizzazione tra Discourse e GitLab
- Rifinitura del processo di revisione e transizione allo stato di preparazione alla pubblicazione della versione finale
- Mantenimento dell’integrità dei collegamenti
- Automazione delle pubblicazioni
- Meccanismo di feedback sulle discrepanze trovate e notifiche sulle correzioni.