Questa pagina è stata tradotta dall'API Cloud Translation.

Progetto Kolibri

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:: Kolibri
Redattore tecnico:: StephDix
Nome del progetto:: Convenzioni relative a stili e flussi di lavoro della documentazione dell'ecosistema Kolibri
Durata del progetto:: A lungo termine (5 mesi)

Project description

Abstract

Questo documento descrive l'implementazione delle linee guida relative allo stile e la gestione del flusso di lavoro nelle informazioni documentate di Learning Equality per il progetto sull'ecosistema Kolibri.

Panoramica

La mia proposta è composta da quattro fasi. Nella prima fase, completerò la Guida di stile alla documentazione di LE con linee guida sull'accessibilità, sulla scrittura e sui formati di consigli, in base ai concetti di LE e alle linee guida di stile nello sviluppo del software. Nella seconda fase, eseguirò un controllo qualità sui documenti di ReadTheDocs e Documenti Google. Il piano di controllo integra l'utilizzo di liste di controllo per valutare la conformità alle linee guida di stile. Questi elenchi di controllo ti aiuteranno a registrare i risultati e ad applicare le modifiche alla documentazione. Nella terza fase, lavorerò alla struttura, all'aspetto e al design dei modelli da ReadTheDocs e Google Docs. Creerò un repository di modelli e immagini su Google Drive che identificherà ogni categoria di modelli dei tipi di documenti principali per il riutilizzo nelle implementazioni future. Completerò questa attività creando modelli per inviare i problemi relativi ai documenti per una facile identificazione nelle revisioni delle richieste di pull. Infine, creerò una Guida per i collaboratori che raggruppa risorse utili per ogni gruppo di collaboratori al fine di migliorare la loro esperienza di accesso alle informazioni.

Scopo e ambito

Lo scopo di questo piano di implementazione è migliorare l'esperienza degli utenti finali utilizzando i documenti di Kolibri e aiutare i membri del team e i collaboratori a produrre una documentazione migliore e una collaborazione attiva all'interno della community. Questa implementazione si applica a ReadTheDocs e ai sottoinsiemi di documenti di Google Documenti nell'ecosistema Kolibri.

Pubblico

I principali utenti che implementano, amministratori e utenti finali sono i consumatori più importanti della documentazione di Kolibri. Un pubblico secondario di membri del team e collaboratori per la produzione e l'utilizzo della documentazione di Kolibri.

Obiettivi

La guida di stile e il sistema di flusso di lavoro per la documentazione dell'ecosistema Kolibri richiedono agli utenti di: Creare una documentazione facilmente comprensibile con un linguaggio accessibile e un layout coerente. Assicurare il mantenimento delle prassi di qualità riportate nella documentazione. Mantieni la facilità di accesso alle informazioni tra i canali di documentazione. Rafforzare le iniziative di collaborazione nella community open source di Kolibri.

Fonti di informazioni

Le mie fonti di informazioni erano Kolibri, Kolibri Studio, i documenti RTD di Kolibri Development e i kit di Kolibri da Google Drive.
La straordinaria Radina Matic è stata di grande aiuto nell'offrire attività di preparazione e attività specifiche per ogni progetto. I suoi contributi su ciò che l'organizzazione concettualizza come ""linee guida"" e ""guide"" e sull'esistenza di una guida per i collaboratori mi hanno aiutato a organizzare le mie idee e a redigere le conclusioni.

Software

Svilupperò la bozza della guida di stile in Documenti Google. Questa piattaforma di documenti è perfetta per eseguire l'iterazione quando è pronta per la pubblicazione. Per il controllo qualità, utilizzerò Moduli Google per condurre e valutare i documenti. Un foglio di lavoro memorizza le risposte del modulo per il controllo dei documenti. Eseguirò il refactoring dei documenti RTD utilizzando GitHub. Ho lavorato con Git, Gitkraken, GitHub e Gitlab. Ho una conoscenza pratica di Markdown e di alcuni RestructuredText. Ho intenzione di contribuire alle correzioni della documentazione per continuare a imparare la sintassi. Userò ShareX per immagini e GIF. Adoro questo strumento perché esegue il rendering in diversi formati di output. Utilizzerò Diagrammi per la creazione di diagrammi e l'editing delle immagini. Il software Diagrams si integra perfettamente con Documenti Google, Google Drive e LibreOffice. Stato della documentazione Nella fase di esplorazione, ho rivisto la maggior parte della documentazione di Kolibri. Ho trovato errori grammaticali, errori ortografici, incoerenze nel layout, nella tipografia, nell'utilizzo delle immagini e percorsi della documentazione confusi nella maggior parte della documentazione del progetto. Ad esempio, nella Guida dell'utente di Kolibri, la sezione relativa alla risoluzione dei problemi è un argomento secondario e non un argomento. Queste informazioni sono abbastanza importanti da richiedere che gli utenti finali possano accedervi dalla tabella dei contenuti. In alternativa, possono utilizzare la barra di ricerca e l'albero della tabella dei contenuti per espandere altri argomenti e trovare gli articoli sulla risoluzione dei problemi.

Per accedere alla sezione "Risoluzione dei problemi", devi cercarla o espandere "Gestisci Kolibri" per renderti conto che la risoluzione dei problemi esiste nella documentazione. Guida e linee guida Per questa proposta di progetto, ho analizzato due documenti: le Guida di stile alla documentazione dell'utente di Kolibri e le linee guida per la traduzione LE. Nella guida LE Kolibri, ho fornito consigli e commenti in base al mio riassunto degli argomenti e al piano di documentazione proposti, oltre ad altre piccole cose che devono essere migliorate nella guida. Per le linee guida per la traduzione di LE, ho modificato il formato e lo stile in base ai miei consigli e alle convenzioni esistenti nella Guida allo stile. Ciò che mi ha colpito di più durante l'analisi è stato il fraintendimento esistente tra i documenti classificati come Guide e Linee guida.

Risultati

Ho eseguito un controllo qualità della Guida alla traduzione di LE, oltre a suggerimenti e commenti con un modulo preliminare che spiego più dettagliatamente nell'attività di controllo qualità. Di seguito sono riportati alcuni commenti finali ottenuti dalla valutazione: Link non funzionanti per il sito web ICU Syntax .js Il formato utilizzato per creare queste linee guida non è corretto. Il documento è una guida, non linee guida. Tipografia incoerente. Utilizzo non corretto di intestazioni e titoli, uso improprio del linguaggio e uso improprio delle contrazioni. Utilizzo improprio dei testi alternativi. Istruzioni/ dichiarazioni ripetute.

I risultati di entrambi i documenti fanno parte dei deliverable di questa proposta.

Attività specifiche del progetto

Consigli (commenti) della Guida di stile per la documentazione dell'utente di LE
Linee guida per le traduzioni di LE con nuovi stili e formato.
Schema dell'argomento
Cronologia del progetto
Attività di documentazione