Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Kolibri
- Rédacteur technique:
- StephDix
- Nom du projet:
- Conventions de style et de workflow pour la documentation de l'écosystème Kolibri
- Durée du projet:
- Longue durée (5 mois)
Project description
Extrait
Ce document décrit l'implémentation des consignes de style et de la gestion des workflows dans les informations documentées de Learning Equality pour le projet d'écosystème Kolibri.
Présentation
Ma proposition comprend quatre phases. Dans la première phase, je vais compléter le guide de style de la documentation LE avec des consignes d'accessibilité, des recommandations d'écriture et de mise en forme, en suivant les concepts et les consignes de style LE dans le développement logiciel. Au cours de la deuxième phase, je procéderai à un audit de la qualité des documents ReadTheDocs et GoogleDocs. Le plan d'audit intègre l'utilisation de checklists pour évaluer la conformité aux consignes de style. Ces checklists vous aideront à enregistrer les résultats et à appliquer les modifications à la documentation. Dans la troisième phase, je vais travailler sur la structure, l'apparence et l'ergonomie des modèles de documents ReadTheDocs et Google Docs. Je créerai un dépôt de modèles et d'images dans Google Drive en identifiant chaque catégorie de modèles des principaux types de documents. Je les réutiliserai dans les prochaines implémentations. Je vais compléter cette tâche en créant des modèles pour signaler les problèmes de document afin de les identifier facilement lors des examens des demandes de tirage. Enfin, je vais créer un guide pour les contributeurs qui regroupera les ressources utiles pour chaque groupe de collaborateurs afin d'améliorer leur expérience d'accès aux informations.
Objet et portée
L'objectif de ce plan d'implémentation 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 de meilleurs documents et à collaborer activement au sein de la communauté. Cette implémentation s'applique à ReadTheDocs et aux sous-ensembles de documents Google Docs dans l'écosystème Kolibri.
Audience
Une audience principale composée d'implémentateurs, d'administrateurs et d'utilisateurs finaux, qui sont les consommateurs les plus importants de la documentation Kolibri. Une audience secondaire composée des membres de l'équipe et des collaborateurs pour la production et l'utilisation de la documentation Kolibri.
Objectifs
Le guide de style et le système de workflow de la documentation de l'écosystème Kolibri s'attendent à ce que les utilisateurs : Créent une documentation facile à lire avec un langage accessible et une mise en page cohérente. Maintenir les pratiques de qualité lors de la documentation. Assurez-vous que les informations sont facilement accessibles entre les canaux de documentation. Renforcer les initiatives de collaboration au sein de la communauté Open Source Kolibri.
Sources d'information
Mes sources d'information étaient Kolibri, Kolibri Studio, les documents RTD sur le développement Kolibri et les kits Kolibri de Google Drive.
La merveilleuse Radina Matic nous a beaucoup aidés à proposer des activités d'échauffement et des activités spécifiques au projet. Ses informations sur ce que l'organisation conceptualise comme des ""consignes"" et des ""guides"", ainsi que sur l'existence d'un guide pour les contributeurs, m'ont aidé à organiser mes idées et à rédiger des conclusions.
Logiciel
Je vais développer le brouillon du guide de style dans Google Docs. Cette plate-forme de documents est idéale pour les itérations lorsqu'elles sont prêtes à être publiées. Pour l'audit de contrôle qualité, je vais utiliser Google Forms pour réaliser et évaluer des documents. Une feuille de calcul stocke les réponses aux formulaires pour le contrôle des documents. Je vais refactoriser les documents RTD à l'aide de GitHub. J'ai travaillé avec Git, Gitkraken, GitHub et Gitlab. Je maîtrise Markdown et quelques-uns des principes de base de RestructuredText. Je prévois de contribuer à la correction de la documentation pour continuer à apprendre la syntaxe. Je vais utiliser ShareX pour les images et les GIF. J'aime cet outil, car il génère des fichiers dans différents formats de sortie. Je vais utiliser Diagrammes pour créer des diagrammes et modifier des images. Le logiciel Diagrams 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 et l'utilisation des images, ainsi que des chemins de documentation confus dans la plupart de la documentation du projet. Par exemple, dans le guide de l'utilisateur de Kolibri, la section consacrée au dépannage est une sous-rubrique et non une rubrique. Ces informations sont suffisamment importantes pour que les utilisateurs finaux y aient accès depuis la table des matières. Ils peuvent également utiliser la barre de recherche et l'arborescence du sommaire pour développer d'autres sujets et trouver des articles de dépannage.
Pour accéder à la section "Dépannage", vous devez la rechercher ou développer "Gérer Kolibri" pour constater qu'elle fait partie de la documentation. Guide et consignes Pour cette proposition de projet, j'ai analysé deux documents : le guide de style de la documentation utilisateur de LE Kolibri et les consignes de traduction de LE. Dans le guide LE Kolibri, j'ai formulé des recommandations et des commentaires à partir de mon plan de documentation et de mon plan de structure des sujets proposés, ainsi que quelques points à améliorer dans le guide. Pour les consignes de traduction de l'anglais vers l'espagnol, j'ai modifié le format et le style en fonction de mes recommandations et des conventions existantes dans le guide de style. Ce qui m'a le plus frappé lors de l'analyse, c'est la confusion qui existe entre les documents classés comme "guide" et "consignes".
Résultats
J'ai effectué un contrôle qualité du guide de traduction pour les langues étrangères, en plus de formuler des suggestions et des commentaires à l'aide d'un formulaire préliminaire que j'explique plus en détail dans la tâche d'audit qualité. Voici quelques commentaires finaux obtenus lors de l'évaluation : Liens non fonctionnels sur le site Web ICU Syntax .js Le format utilisé pour créer ces consignes est incorrect. Il s'agit d'un guide, et non de consignes. Typographie incohérente. Utilisation incorrecte des titres et des titres, utilisation inappropriée du langage et utilisation abusive des contractions. Utilisation incorrecte des textes alternatifs. Avec des instructions/ déclarations répétées.
Les résultats des deux documents font partie des livrables de cette proposition.
Tâches spécifiques au projet
- Recommandations du guide de style pour la documentation utilisateur LE (commentaires)
- de LE Translation avec de nouveaux styles et formats.
- Structure du sujet
- Calendrier du projet
- Tâches de documentation