Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Kolibri
- Rédacteur technique:
- StephDix
- Nom du projet:
- Conventions concernant le style de documentation et les workflows de l'écosystème Kolibri
- Durée du projet:
- Exécution longue (5 mois)
Project description
Abstraite
Ce document détaille l'implémentation des consignes de style et de la gestion des flux de travail dans les informations documentées de Learning Equality pour le projet Kolibri Ecosystem.
Présentation
Ma proposition se compose de quatre phases. Dans la première phase, je compléterai le guide de style de la documentation LE avec des consignes d'accessibilité, de rédaction et de format, tout en respectant les concepts de LE et les consignes de style pour le développement de logiciels. Lors de la deuxième phase, j'effectuerai un audit de la qualité sur les documents ReadTheDocs et GoogleDocs. Le plan d'audit intègre l'utilisation de listes de contrôle pour évaluer le respect des consignes de style. Ces listes de contrôle vous aideront à enregistrer les résultats et à appliquer les modifications à la documentation. Lors de la troisième phase, je travaillerai sur la structure, l'apparence et le rendu des modèles issus de ReadTheDocs et des documents GoogleDocs. Je vais créer un dépôt de modèles et d'images dans Google Drive, identifiant chaque catégorie de modèle pour les principaux types de documents, pour les réutiliser dans les prochaines implémentations. Je vais compléter cette tâche en créant des modèles pour soumettre les problèmes de documents afin de les identifier facilement dans les examens des demandes d'extraction. Enfin, je vais créer un guide des contributeurs qui regroupera des ressources utiles pour chaque groupe de collaborateurs afin d'améliorer leur expérience d'accès aux informations.
Objectif et portée
L'objectif de ce plan de mise en œuvre est d'améliorer l'expérience des utilisateurs finaux qui utilisent les documents de Kolibri et d'aider les membres de l'équipe et les contributeurs à produire une meilleure documentation et une collaboration active au sein de la communauté. Cette implémentation s'applique à ReadTheDocs et aux sous-ensembles de documents Google Docs de l'écosystème Kolibri.
Audience
Les utilisateurs les plus importants de la documentation Kolibri sont les principaux utilisateurs de la mise en œuvre, des administrateurs et des utilisateurs finaux. Audience secondaire de membres de l'équipe et de collaborateurs pour la production et l'utilisation de la documentation Kolibri.
Objectifs
Guide de style et système de workflow pour l'écosystème Kolibri La documentation demande aux utilisateurs de : Créer une documentation digeste avec un langage accessible et une mise en page cohérente. Préservez le maintien de pratiques de qualité en vous appuyant sur la documentation. Faciliter l'accès aux informations entre les canaux de documentation Renforcer les initiatives de collaboration au sein de la communauté Open Source de Kolibri
Sources d'information
Les sources d'informations dont je dispose sont Kolibri, Kolibri Studio, les documents Kolibri Development RTD et les kits Kolibri de Google Drive.
La merveilleuse Radina Matic a été d'une grande aide en fournissant des activités de préparation et des activités spécifiques à chaque projet. Sa contribution à ce que l'organisation considère comme des "directives" et des ""guides" et concernant l'existence d'un guide pour les contributeurs m'a aidé à organiser mes idées et à tirer des conclusions.
Logiciels
Je créerai le brouillon du guide de style dans Google Docs. Cette plate-forme de documents est idéale pour itérer tant qu'elles sont prêtes à être publiées. Pour l'audit de contrôle qualité, je réaliserai et évaluerai les documents à l'aide de Google Forms. Une feuille de calcul stockera les réponses au formulaire pour contrôler les documents. Je vais refactoriser les documents RTD à l'aide de GitHub. J'ai travaillé avec Git, Gitkraken, GitHub et Gitlab. J'ai une connaissance pratique de Markdown et de quelques RestructuredText. Je prévois de contribuer aux corrections de la documentation pour continuer à apprendre la syntaxe. J'utiliserai Sharex pour les images et les GIF. J'adore cet outil, car il effectue un rendu dans différents formats de sortie. j'utiliserai des diagrammes pour les diagrammes et l'édition d'images. Le logiciel de diagrammes s'intègre parfaitement à Google Docs, Google Drive et LibreOffice. État de la documentation Au cours de la phase d'exploration, j'ai révisé la majeure partie de la documentation de Kolibri. J'ai trouvé des erreurs grammaticales, des fautes de frappe, des incohérences dans la mise en page, la typographie, l'utilisation des images et aussi, des chemins de documentation déroutants dans la plupart de la documentation du projet. Par exemple, dans le guide de l'utilisateur de Kolibri, la section de dépannage est un sous-sujet et non un sujet. Ces informations sont suffisamment importantes pour que les utilisateurs finaux puissent y accéder à partir de la table des matières. Il peut également utiliser la barre de recherche et l'arborescence de table des matières pour développer d'autres sujets et trouver des articles de dépannage.
Pour accéder à la section "Dépannage", recherchez-la ou développez "Manage Kolibri" (Gérer Kolibri) pour vous rendre compte que la section "Dépannage" fait partie de la documentation. Guide vs Guidelines Pour cette proposition de projet, j'ai analysé deux documents : LE Kolibri User Documentation Style Guide and LE Translation Guidelines. Dans le guide LE Kolibri, j'ai fait des recommandations et des commentaires à partir de ma proposition de sujet et de mon plan de documentation, ainsi que d'autres choses à améliorer sur le guide. Pour les directives de traduction LE, j'ai modifié le format et le style en fonction de mes recommandations et des conventions existantes du guide de style. Ce qui m'a le plus attiré lors de l'analyse, c'est l'idée fausse qui existe entre les documents classés comme "Guides" et "Consignes".
Résultats
J'ai effectué un contrôle qualité sur le guide de traduction LE, ainsi que des suggestions et des commentaires avec un formulaire préliminaire que j'expliquerai plus en détail dans la tâche d'audit de contrôle qualité. Voici les derniers commentaires obtenus lors de l'évaluation : Liens non fonctionnels pour le site Web utilisant la syntaxe ICU .Le format utilisé pour créer ces consignes est incorrect. Il s'agit d'un guide, et non d'un guide. Typographie incohérente. Utilisation incorrecte des en-têtes et des titres, Utilisation inappropriée du langage et des contractions. Utilisation incorrecte d'autres textes. Les déclarations/ instructions répétées.
Les résultats des deux documents font partie des produits livrables de cette proposition.
Tâches spécifiques au projet
- Recommandations du guide de style de la documentation utilisateur LE (commentaires)
- LE Translation avec de nouveaux styles et formats.
- Plan du sujet
- Calendrier du projet
- Tâches de documentation