Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- La base di Linux
- Technical writer:
- boro
- Nome progetto:
- Rielabora le pagine introduttive per l'hosting e la generazione e la ristrutturazione e le guide per gli sviluppatori.
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Riassunto :
La documentazione è pensata per aiutare gli utenti finali e gli sviluppatori a utilizzare un prodotto o servizio. Una buona documentazione è molto importante perché offre agli utenti la possibilità di imparare a utilizzare un software, le sue funzionalità e suggerimenti, nonché a 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 sviluppatori.
Senza una buona documentazione, un utente potrebbe non sapere come svolgere le attività sopra indicate in modo efficace ed efficiente. La documentazione può 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; un'ottima documentazione prende questa comunicazione e la mette in una struttura gestibile a cui tutti possono accedere per il successo.
Ogni sito di documentazione ha bisogno di una buona pipeline di flusso di lavoro per la creazione e l'hosting, in un'organizzazione come AGL, con più versioni e molta documentazione elaborata, i file di documentazione (markdown) sono distribuiti su più repository, rendendo le attività di manutenzione e aggiornamento incredibilmente complesse e dispendiose in termini di tempo.
Stato attuale :
- Il sito web AGL doc si basa su una raccolta di file di markdown recuperati da vari repository.
- Le pagine del documento sono attualmente ospitate all'interno delle singole fonti come markdown utilizzando il motore del progetto cordova.
- Questo porta alla configurazione di quattro repository per il processo di compilazione e hosting della documentazione :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : contiene il modello del sito web Jekyll.
- Documenti-Strumenti [https://github.com/automotive-grade-linux/docs-tools] : contiene strumenti per generare automaticamente un sito web tecnico dai file Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : fonte (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) per documenti e guide generali.
- 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 della 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 di markdown in base al fetched_files.yml che si trova in docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- L'attuale flusso di lavoro per la generazione del sito web con la documentazione agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- La section_version.yml contiene i link a tutti i file YAML dei libri, procede con il recupero di tutti i file YAML dei libri da repository remoti a docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. I file YAML dei libri contengono tutti gli URL dei tuoi file di markdown del repository remoto.
- Non appena vengono recuperati tutti i file di markdown, 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.
- L'attuale processo di gestione della pipeline non è facile da usare e per sviluppatori, soprattutto per i nuovi collaboratori. Questa pipeline del flusso di lavoro (di creazione e hosting) può essere semplificata e semplificata maggiormente per consentire agli sviluppatori di concentrarsi sulla parte relativa alla documentazione piuttosto che mantenere il flusso di lavoro di generazione e deployment della documentazione.