Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- I concetti di base di Linux
- Technical writer:
- boro
- Nome progetto:
- Rielabora le pagine introduttive e le guide per gli sviluppatori relative a hosting e generazione e ristrutturazione della documentazione.
- 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é fornisce agli utenti un mezzo per imparare a utilizzare un software, le sue funzioni, suggerimenti, trucchi e anche risolvere problemi comuni riscontrati durante l'utilizzo del software. Inoltre, riduce i costi di assistenza ed è parte dell'identità aziendale e open source del prodotto : una buona documentazione è un segnale di integrità del prodotto e del team di sviluppatori.
Senza una buona documentazione, un utente potrebbe non essere in grado di svolgere le operazioni sopra descritte 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, mentre un'ottima documentazione si limita a questa comunicazione e la inserisce in un framework 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 in più repository, rendendo il lavoro di manutenzione e aggiornamento incredibilmente complesso e dispendioso in termini di tempo.
Stato attuale :
- Il sito web per documenti AGL si basa su una raccolta di file di markdown recuperati da vari repository.
- Le pagine del documento sono attualmente ospitate all'interno delle singole origini come markdown utilizzando il motore del progetto Cordova.
- Questo porta alla 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 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] : deployment del repository di pagine GitHub 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 definire 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].
- Flusso di lavoro attuale per la generazione di siti web con 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 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 dal repository remoto.
- Non appena tutti i file di 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 procedura di gestione della pipeline non è facile da usare e per gli sviluppatori, soprattutto per i nuovi collaboratori. Questa pipeline del flusso di lavoro (di creazione e hosting) può essere semplificata e semplificata per consentire agli sviluppatori di concentrarsi sulla parte della documentazione piuttosto che mantenere il flusso di lavoro di generazione e deployment della documentazione.