Progetto Kolibri

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:

Kolibri

Technical writer:

StephDix

Nome progetto:

Stile di documentazione dell'ecosistema di Kolibri e convenzioni dei flussi di lavoro

Durata del progetto:

Lunga esecuzione (5 mesi)

Project description

Abstract

Questo documento descrive in dettaglio l'implementazione delle linee guida di Style e la gestione del flusso di lavoro per le informazioni documentate di Learning Equality per il progetto dell'ecosistema di Kolibri.

Panoramica

La mia proposta si compone di quattro fasi. Nella prima fase, completerò la LE Documentazione di stile guida con linee guida per l'accessibilità, scrittura e consigli per il formato seguendo i concetti di LE e le linee guida di stile nello sviluppo del software. Nella seconda fase, eseguirò un controllo qualità sui documenti ReadTheDocumenti e GoogleDocumenti. Il piano di controllo integra l'utilizzo di elenchi di controllo per valutare la conformità alle linee guida di stile. Questi elenchi di controllo sono utili per registrare i risultati e applicare modifiche alla documentazione. Nella terza fase, mi occuperò della struttura, dell'aspetto e del design dei modelli dai documenti ReadTheDocumenti e GoogleDocumenti. Creerò un repository di modelli e immagini su Google Drive identificando ogni categoria di modello dei principali tipi di documenti da riutilizzare nelle prossime implementazioni. Complerò questa attività di creazione di modelli per inviare problemi relativi ai documenti in modo da facilitarne l'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 propria esperienza di accesso alle informazioni.

Scopo e ambito

L'intenzione alla base di questo piano di implementazione è migliorare l'esperienza degli utenti finali che utilizzano i documenti di Kolibri e aiutare i membri del team e i collaboratori a produrre una documentazione migliore e una collaborazione attiva nella comunità. Questa implementazione si applica a ReadTheDocs e ai sottoinsiemi di documenti di Documenti Google nell'ecosistema di Kolibri.

Pubblico

Un pubblico principale composto da responsabili dell'implementazione, amministratori e utenti finali che è il consumatore più critico 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 sull'ecosistema di Kolibri richiede agli utenti di: Creare una documentazione digeribile con un linguaggio accessibile e un layout coerente. Preservare il mantenimento delle pratiche di qualità sulla documentazione. Mantieni un facile accesso alle informazioni tra i canali di documentazione. Rafforza 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 Kolibri Toolkits di Google Drive.
La meravigliosa Radina Matic è stata di grande aiuto nel fornire attività di riscaldamento e attività specifiche per i progetti. Il suo contributo su ciò che l'organizzazione concettualizza come ""Linee guida" e "Guide" e sull'esistenza di una Guida per i collaboratori mi ha aiutato a organizzare le mie idee e le mie conclusioni.

streaming

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 memorizzerà 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 oggetti 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 la versione di immagini. Il software per i diagrammi si integra perfettamente con Documenti Google, Google Drive e LibreOffice. Stato della documentazione Nella fase di esplorazione, ho rivisto gran parte della documentazione di Kolibri. Ho trovato errori grammaticali, errori di battitura, incongruenze a livello di layout, tipografia, utilizzo delle immagini e anche percorsi di documentazione confusi con la 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 sufficientemente fondamentali per consentire agli utenti finali di accedervi dal sommario. In alternativa, possono utilizzare la barra di ricerca e la struttura del sommario per espandere altri argomenti e individuare gli articoli per la risoluzione dei problemi.

Per accedere alla sezione "Risoluzione dei problemi", devi cercarla o espandere "Gestisci Kolibri" per capire che la sezione Risoluzione dei problemi fa parte della documentazione. Guida e linee guida Per questa proposta di progetto, ho analizzato due documenti: la guida di stile per la documentazione dell'utente di LE Kolibri e le linee guida per la traduzione di LE. Nella guida di LE Kolibri, ho fornito consigli e commenti sulla struttura dell'argomento e sul piano di documentazione che ho proposto, oltre ad altri aspetti della guida che richiedono un miglioramento. Per quanto riguarda le linee guida per la traduzione di LE, ho modificato il formato e lo stile in base ai miei consigli e alle convenzioni esistenti della guida di stile. Durante l'analisi ho notato un equivoco che esiste tra i documenti classificati come Guida e Linee guida.

Risultati

Ho eseguito un controllo di qualità della Guida alla traduzione di LE, oltre a suggerimenti e commenti, con un modulo preliminare che spiegherò più dettagliatamente nell'attività di controllo del QA. Ecco alcuni commenti finali ottenuti dalla valutazione: Link inaccessibili per il sito web .js per la sintassi ICU Il formato utilizzato per creare queste linee guida non è corretto. Il documento è una guida, non una guida. Tipografia incoerente. Uso non corretto di intestazioni e titoli, Uso improprio del linguaggio e uso improprio delle contrazioni. Uso improprio di testi alternativi. Sopra istruzioni/ istruzioni ripetute.

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

Attività specifiche del progetto

• Consigli della Guida di stile per la documentazione dell'utente di LE (commenti)
• LE Translation Guidelines con nuovi stili e formati.
• Struttura dell'argomento
• Cronologia del progetto
• Attività relative alla documentazione