Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- The Linux Foundation
- Redattore tecnico:
- boro
- Nome del progetto:
- Rivedere l'hosting e la generazione della documentazione e riorganizzare le pagine di inizio e le guide per gli sviluppatori.
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Abstract :
La documentazione è concepita per aiutare gli utenti finali e gli sviluppatori a utilizzare un prodotto o servizio. Una buona documentazione è molto importante perché offre agli utenti un mezzo per imparare a utilizzare un software e le sue funzionalità, consigli e suggerimenti, oltre a risolvere i problemi comuni riscontrati durante l'utilizzo del software. Inoltre, riduce i costi di assistenza e fa parte dell'identità aziendale e open source del prodotto : una buona documentazione è un segno di salute del prodotto e del team di sviluppatori.
Senza una buona documentazione, un utente potrebbe non sapere come eseguire le operazioni precedenti in modo efficace ed efficiente. La documentazione può svolgere un ruolo fondamentale per garantire il successo di un prodotto perché una comunicazione efficace è e sarà sempre al centro di qualsiasi attività o prodotto e una buona documentazione prende questa comunicazione e la inserisce in un framework gestibile a cui tutti possono accedere per ottenere risultati.
Ogni sito di documentazione ha bisogno di una buona pipeline di flusso di lavoro di compilazione e hosting. In un'organizzazione come AGL, con più versioni e molta documentazione elaborata, i file di documentazione (markdown) sono distribuiti su più repository, il che rende l'attività di manutenzione e aggiornamento incredibilmente complessa e dispendiosa in termini di tempo.
Stato attuale :
- Il sito web di documento AGL si basa su una raccolta di file markdown recuperati da vari repository.
- Al momento le pagine dei documenti sono ospitate all'interno delle singole origini come Markdown utilizzando il motore del progetto Cordova.
- Ciò comporta la configurazione di quattro repository per la compilazione e l'hosting della documentazione :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : contiene il modello di sito web Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : contiene strumenti per generare automaticamente un sito web tecnico da file Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : codice sorgente (markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) per documenti generali e guide.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : repository di pagine GitHub di cui è stato eseguito il deployment per il sito di documentazione [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Uno strumento (script) disponibile in docs-tools [https://github.com/automotive-grade-linux/docs-tools] si occupa di raccogliere e creare modelli di tutti i file Markdown in base al fetched_files.yml che si trova in docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Il flusso di lavoro attuale per la generazione del sito web della documentazione agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- Il file section_version.yml contiene i link a tutti i file yaml del libro e recupera tutti i file yaml del libro dai repository remoti in docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. I file YAML dei libri contengono tutti gli URL dei tuoi file di markdown dal repository remoto.
- Non appena tutti i file markdown vengono recuperati, gli strumenti elaborano il sito web del documento AGL in docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] di cui viene eseguito il deployment corrispondente.
- L'attuale processo di gestione della pipeline non è user-friendly e non è adatto agli sviluppatori, in particolare ai nuovi collaboratori. Questa pipeline di flusso di lavoro (di compilazione e hosting) può essere semplificata e ottimizzata in modo che gli sviluppatori possano concentrarsi sulla parte di documentazione anziché gestire il flusso di lavoro di generazione e deployment della documentazione.