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:
- WordPress
- Rédacteur technique:
- tacionique
- Nom du projet:
- Un guide de style pour la documentation complet et renouvelé
- Durée du projet:
- Exécution longue (5 mois)
Project description
Synopsis :
WordPress est une organisation mondiale de logiciels à but non lucratif qui a pour mission de servir les communautés du monde entier avec des logiciels qui mettent l'accent sur l'accessibilité, les performances, la sécurité et la facilité d'utilisation. L'objectif de WordPress est de démocratiser l'édition et les logiciels Open Source sur le Web. À notre ère numérique, un site Web est littéralement la façade en ligne d'une organisation/d'un individu. WordPress accomplit une tâche immense qui consiste à servir efficacement des centaines de millions d'utilisateurs (ce qui est attribué aux 35% d'Internet qu'il utilise) avec leur logiciel. La documentation s'avère essentielle pour mieux répondre aux besoins de ces utilisateurs. Elle est utilisée par la plupart des développeurs, des administrateurs et des utilisateurs finaux. Par conséquent, la documentation peut être définie comme un facteur principal de l'écosystème WordPress. La documentation actuelle de WordPress n'inclut pas d'ensemble universel et unifié de règles et de consignes de style pour la publication. L'objectif de cette proposition est de créer un ensemble complet et renouvelé de consignes de style de documentation, universellement applicables à la documentation WordPress. L'idée du projet consiste à consolider tous les aspects des directives de conception et de style tels que la sémantique, la syntaxe, les directives grammaticales, la ponctuation, les règles spécifiques au développement, les attributs de conception et les spécificités de la mise en forme. Il intègre également des conventions linguistiques telles que la voix, le ton, le temps, tous les éléments de discours, ainsi que les conventions de nommage. Les outils, langages et plates-formes utilisés sont WordPress CMS, GitHub et Markdown. Ils peuvent également être constitués de PHP/MySQL, HTML/CSS et JavaScript.
Plan du projet:
Guides de style pour la documentation WordPress sur l'état actuel : L'équipe de documentation de WordPress a mis en œuvre une méthodologie non déclarée, mais unanime, pour respecter les consignes de publication. Cependant, de temps en temps, certains éléments sont présupposés et le processus devient spéculatif. Il n'existe pas de norme ni de critère fixe pour rédiger et publier des articles pour WordPress. L'équipe de documentation a rédigé des directives de style spécifiques au projet, mais aucune n'est universellement applicable. La plupart des consignes de style qui existent ne sont pas regroupées dans un seul manuel, ou sont obsolètes et doivent être mises à jour. Par conséquent, il est nécessaire de concevoir et de développer un guide de style unifié pour standardiser la documentation de WordPress.
Objectifs :
Plus de 35% des sites Web d'Internet sont exécutés sur WordPress, ce qui indique que des millions de développeurs et d'utilisateurs finaux exploitent les fonctionnalités impressionnantes de WordPress. La documentation est un élément essentiel pour aider ces développeurs et ces utilisateurs à exécuter efficacement ces fonctionnalités sans aucun tracas, même en cas de désagrément. L'objectif général de cette proposition de projet est de standardiser un guide de conception et de style, d'unifier les guides de style existants et de le mettre à jour, ainsi que d'ajouter de nouvelles réglementations et spécifications pour la documentation WordPress. Cela permettrait la facilité d'utilisation, la simplicité et l'uniformité de la documentation WordPress.
Mise en œuvre :
Comme suggéré par le mentor (Jon Ang) pour ce projet, celui-ci peut être abordé en quatre phases: découverte, définition, mise en œuvre et maintenance. Avant le début du projet, pendant la période de pré-stage, je travaillerai avec mon mentor et je finaliserai un calendrier et un calendrier appropriés en fonction de mon calendrier et des produits livrables suivants. Je vais me familiariser davantage avec le système WordPress et les protocoles de travail pour ce projet.
Au début du stage, je discuterai et préparerai l'extrait du plan avec mon mentor. Les exigences et les besoins seront déterminés. Tout d'abord, je vais décrire le flux de la documentation et le processus d'interaction utilisateur. Ensuite, les maquettes de mise en page de chaque section, catégorie et composant seront décrites. Ces mises en page seront ensuite examinées par mon mentor. Si nécessaire, les mises en page seront repensées et certains composants seront ajoutés/supprimés. Je réaliserai ensuite des recherches sur les utilisateurs afin de déterminer la facilité d'utilisation et la faisabilité du flux d'interface. Par la suite, le guide de style de la documentation sera implémenté par section (comme illustré dans le schéma ci-dessous). Vous pouvez également consulter les guides de style d'autres organisations qui sont sous licence Open Source ou Creative Commons afin d'y ajouter également notre guide. Si, au cours de cette période, des problèmes d'utilisabilité se produisent, je les remanierai.
Les tests et les optimisations seront effectués une fois le guide de style terminé et intégré à HelpHub. Toutes les vulnérabilités, éléments redondants ou composants seraient rectifiés. L'interface utilisateur et le code seront testés, et les erreurs et bugs indésirables seront corrigés, si nécessaire. Un contrôle final de la qualité du guide de style complet sera effectué pour la langue, la grammaire, l'orthographe, la ponctuation, etc.
Les tâches en attente en raison de retards imprévus seront terminées pendant la période tampon. Des fonctionnalités ou caractéristiques supplémentaires qui seraient déterminées comme réalisables au cours du projet peuvent être implémentées après la fin des tests finaux. Un plan de déploiement serait élaboré et le produit fini sera soumis.
Outils et méthodologies:
La documentation sera compilée et modifiée sur une plate-forme collaborative telle que Google Docs. Si la publication doit être effectuée via GitHub, les langages de balisage tels que Markdown ou GitHub Flavored Markdown peuvent également être implémentés. Pour les normes de conception et de style, vous pouvez également vous référer aux directives de style Open Source. Enfin, le document complété sera mis en forme et publié à l'aide de WordPress.
Table des composants:
Il s'agit d'une liste exhaustive des composants que vous pouvez mettre en œuvre dans le guide de style. Directives des documents : accessibilité, structure des documents, encodage, sources externes, faits, polices, audience mondiale, inclusion, légalité, accessibilité multiplate-forme, non ambiguë, aucune déclaration excessive, mise en page, exactitude politique, protocoles, sécurité, structure des phrases, rédaction succincte, ton et style, impartial
Langue et grammaire - Abréviations et acronymes, Affirmation et négation, Articles, Majuscules, Clause, Discours direct/indirect, Première/Deuxième/Troisième personne, Genres, Glossaire, Noms, Préfixes et suffixes, Prépositions, Pronoms, Références, Argot et jargon, Orthographe, termes techniques, Tense
Ponctuation - Apostrophe et guillemets, deux points et demi-virgules, virgules, ellipses, points d'exclamation, traits d'union et tirets, parenthèses, points, points d'interrogation, barres obliques
Mise en forme - extraits, introduction, préfaces, noms de marques, noms de produits, légendes, extraits de code, blocs de code, date et heure, fuseaux horaires, lieux, devises, noms de fichiers, notes de bas de page, numéros de brevets, mises en surbrillance (gras, italique, souligné, texte barré, avertissements, guillemets), mise en page, index, liens et URL, listes à puces, texte
Interface utilisateur - Activités, boutons, extraits de code, blocs de code, interface de ligne de commande, boîtes de dialogue, menus et menus déroulants, fenêtres pop-up et alertes, onglets, terminologie, éléments d'interface utilisateur, Windows
Code : CSS, HTML, JS, Markdown, MySQL, PHP, syntaxe, XML
Dictionnaire de vocabulaire/Glossaire - A à Z