Questa pagina contiene i dettagli di un progetto di redazione tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- The Linux Foundation
- Technical Writer:
- boron
- Nome del progetto:
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Abstract :
Una documentazione è progettata per aiutare gli utenti finali e gli sviluppatori a utilizzare un prodotto o un servizio. Una buona documentazione è molto importante perché fornisce agli utenti un modo per imparare a utilizzare un software, le sue funzionalità, suggerimenti, trucchi e anche per risolvere i problemi comuni riscontrati durante l'utilizzo del software. Riduce inoltre i costi di assistenza e fa parte dell'identità aziendale e open source del prodotto : una buona documentazione è un segno di integrità del prodotto e del team di sviluppo.
Senza una buona documentazione, un utente potrebbe non sapere come eseguire le operazioni sopra descritte in modo efficace ed efficiente. Le documentazioni possono svolgere un ruolo fondamentale nel garantire il successo di un prodotto, perché un'ottima comunicazione è e sarà sempre al centro di qualsiasi attività o prodotto e una documentazione di qualità inserisce questa comunicazione in un framework gestibile a cui tutti possono accedere per avere successo.
Ogni sito di documentazione ha bisogno di una buona pipeline di workflow di creazione e hosting. In un'organizzazione come AGL, con più versioni e molta documentazione elaborativa, 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 della documentazione AGL si basa su una raccolta di file Markdown recuperati da vari repository.
- Le pagine della documentazione sono attualmente ospitate nelle singole origini come Markdown utilizzando il motore del progetto Cordova.
- Ciò comporta una configurazione di quattro repository per il processo di creazione e 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] : origine (markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) per documenti generali, guide.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : repository delle 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 file fetched_files.yml che si trova in docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Il workflow attuale di 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 dei libri. Procede al recupero di tutti i file YAML dei libri dai repository remoti in docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. I file YAML dei libri contengono tutti gli URL dei file Markdown del repository remoto.
- Non appena vengono recuperati tutti i file Markdown, gli strumenti procedono alla generazione del sito web della documentazione AGL in docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], di cui viene eseguito il deployment di conseguenza.
- L'attuale processo di manutenzione della pipeline non è facile da usare per gli utenti e gli sviluppatori, soprattutto per i nuovi contributori. Questa pipeline di workflow (di creazione e hosting) può essere semplificata e ottimizzata molto di più per consentire agli sviluppatori di concentrarsi sulla parte di documentazione anziché sulla manutenzione del workflow di generazione e deployment della documentazione.