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 liées au style de documentation et aux workflows de l'écosystème Kolibri
- Durée du projet:
- Exécution de longue durée (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 comprend quatre phases. Dans la première phase, je compléterai le guide de style de la documentation LE avec les consignes d'accessibilité, la rédaction et le format des recommandations sur la base des concepts de LE et des consignes de style applicables au développement de logiciels. Lors de la deuxième phase, j'effectuerai un audit de la qualité des documents ReadTheDocs et GoogleDocs. Le plan d'audit intègre l'utilisation de checklists 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'aspect et la convivialité des modèles à partir de ReadTheDocs et des documents GoogleDocs. Je vais créer un dépôt de modèles et d'images dans Google Drive en identifiant chaque catégorie de modèles pour les principaux types de documents, que je pourrai réutiliser dans les prochaines mises en œuvre. Je vais compléter cette tâche en créant des modèles pour envoyer les problèmes de documents afin de les identifier facilement lors de l'examen des demandes d'extraction. Enfin, je vais créer un guide pour les 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 Kolibri et d'aider les membres de l'équipe et les contributeurs à produire une meilleure documentation et à collaborer activement avec la communauté. Cette implémentation s'applique à ReadTheDocs et aux sous-ensembles de documents Google Docs de l'écosystème Kolibri.
Audience
Audience principale composée de professionnels, d'administrateurs et d'utilisateurs finaux, qui sont les utilisateurs les plus importants de la documentation de Kolibri. Une audience secondaire de membres de l'équipe et de collaborateurs chargés de la production et de l'utilisation de la documentation Kolibri.
Objectifs
Guide de style et système de workflow pour la documentation de l'écosystème Kolibri s'adresse aux utilisateurs : Créer une documentation digeste avec un langage accessible et une mise en page cohérente. Préservez le maintien de pratiques de qualité sur la documentation. Facilitez l'accès aux informations entre les canaux de documentation. Renforcez les initiatives de collaboration de la communauté Open Source de Kolibri.
Sources d'information
Les sources d'informations dont je disposais figuraient sur Kolibri, Kolibri Studio, les documents Kolibri Development RTD et les kits Kolibri issus de Google Drive.
La splendide Radina Matic m'a été d'une aide précieuse en organisant des activités d'échauffement et des activités spécifiques au 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 à rédiger mes 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'il est prêt à être publié. 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 le contrôle des 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 à la correction de la documentation pour continuer à apprendre la syntaxe. J'utiliserai Sharex pour les images et les gifs. 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 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, l'utilisation d'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 depuis 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 rubriques et trouver des articles de dépannage.
Pour accéder à la section "Dépannage", recherchez-la ou développez la section "Manage Kolibri" (Gérer Kolibri). Guide vs consignes Pour cette proposition de projet, j'ai analysé deux documents : LE Kolibri User Documentation Style Guide et LE Translation Guidelines. Dans le guide LE Kolibri, j'ai fait des recommandations et des commentaires à partir de mon plan de sujet et de mon plan de documentation, ainsi que d'autres éléments à améliorer. Pour les directives LE Translation, 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 marqué lors de l'analyse, c'est l'idée fausse qui existe entre les documents classés dans les catégories "Guide" et "Consignes".
Résultats
J'ai effectué un contrôle qualité sur le guide de traduction LE, auquel j'ai fait part de mes suggestions et de mes commentaires à l'aide d'un formulaire préliminaire que j'explique 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 .js avec syntaxe ICU Le format utilisé pour créer ces consignes est incorrect. Le document est un guide, et non des 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. Déclarations/ instructions répétées trop souvent.
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 Guidelines avec de nouveaux styles et formats.
- Plan du sujet
- Calendrier du projet
- Tâches de documentation