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:
- WordPress
- Rédacteur technique:
- tactonique
- Nom du projet:
- Un ensemble complet et renouvelé du guide de style de la documentation
- Durée du projet:
- Longue durée (cinq mois)
Project description
Synopsis :
WordPress est une organisation logicielle à but non lucratif internationale qui se consacre à fournir aux communautés du monde entier des logiciels qui mettent l'accent sur l'accessibilité, les performances, la sécurité et la facilité d'utilisation. WordPress s'efforce de démocratiser la publication et les logiciels Open Source sur le Web. À notre époque numérique, un site Web est littéralement la façade en ligne d'une organisation ou d'un individu. WordPress a la lourde tâche de servir efficacement des centaines de millions d'utilisateurs (35% d'Internet) avec son logiciel. Pour mieux répondre aux besoins de ces utilisateurs, la documentation s'avère essentielle et est utilisée par la plupart des développeurs, administrateurs et utilisateurs finaux. Par conséquent, la documentation peut être considérée comme un facteur principal de l'écosystème WordPress. La documentation WordPress actuelle 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, applicables universellement à la documentation WordPress. L'idée de projet consiste à consolider tous les aspects des directives de conception et de style telles 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 mise en forme. Il intègre également les conventions linguistiques telles que la voix, le ton, le temps, toutes les parties du discours, ainsi que les conventions d'attribution de noms. Les outils, langages et plates-formes utilisés seront le CMS WordPress, GitHub, Markdown, et peuvent également inclure PHP/MySQL, HTML/CSS et JavaScript.
Plan du projet:
État actuel des guides de style de la documentation WordPress : l'équipe de documentation WordPress a mis en œuvre une méthodologie non déclarée, mais unanime, pour les consignes de publication. Mais 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 écrire et publier des articles pour WordPress. L'équipe de documentation a rédigé des consignes de style spécifiques au projet, mais aucune ne s'applique universellement. La plupart des consignes de style existantes ne sont pas regroupées dans un seul manuel, ou sont obsolètes et doivent être mises à jour. Il est donc nécessaire de concevoir et de développer un guide de style unifié pour standardiser la documentation WordPress.
Objectifs :
Plus de 35% des sites Web d'Internet fonctionnent sur WordPress, ce qui signifie que des millions de développeurs et d'utilisateurs finaux utilisent les fonctionnalités impressionnantes de WordPress. La documentation est un élément essentiel pour aider ces développeurs et utilisateurs à utiliser efficacement ces fonctionnalités sans tracas, même en cas de désagréments. L'objectif global de cette proposition de projet est de normaliser un guide de conception et de style, d'unifier les guides de style existants et de les mettre à jour, ainsi que d'ajouter de nouvelles règles et spécifications pour la documentation WordPress. Cela permettrait de faciliter l'utilisation, la simplicité et l'uniformité de la documentation WordPress.
Mise en œuvre :
Comme suggéré par le mentor (Jon Ang) pour ce projet, il peut être abordé en quatre phases: découverte, définition, implémentation et maintenance. Avant le début du projet, pendant la période précédant l'internship, je travaillerai avec mon mentor pour finaliser un calendrier et un calendrier adaptés, en fonction de mon calendrier et de mes livrables ultérieurs. Je vais me familiariser davantage avec le système WordPress et les protocoles de travail pour ce projet.
Au début de l'internship, je discuterai et rédigerai le résumé 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 de l'utilisateur. Ensuite, les maquettes fonctionnelles 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 ou supprimés. Je vais ensuite mener des recherches sur l'expérience utilisateur pour déterminer l'usabilité et la faisabilité du parcours utilisateur. Par la suite, le guide de style de la documentation sera implémenté (comme illustré dans le diagramme ci-dessous) par section. Vous pouvez également vous reporter aux guides de style d'autres organisations sous licence Open Source ou Creative Commons en complément de notre guide. Si des difficultés d'usabilité surviennent pendant cette période, je les redéfinirai.
Les tests et les optimisations seront effectués une fois le guide de style finalisé et intégré à HelpHub. Toute vulnérabilité, tout élément ou composant redondant sera corrigé. Des tests de l'interface utilisateur et du code seront effectués, et les bugs et erreurs indésirables seront corrigés, si nécessaire. Un contrôle qualité final sera effectué sur l'ensemble du guide de style pour vérifier la langue, la grammaire, l'orthographe, la ponctuation, etc.
Les tâches en attente en raison de retards imprévus seront effectuées pendant la période tampon. Les fonctionnalités supplémentaires qui seront jugées réalisables au cours du projet peuvent être implémentées une fois les tests finaux effectués. Un plan de déploiement serait élaboré et le produit fini serait soumis.
Outils et méthodologies:
La documentation sera compilée et modifiée sur une plate-forme collaborative, telle que Google Docs. Si vous devez publier via GitHub, vous pouvez également implémenter des langages de balisage tels que Markdown ou GitHub Flavored Markdown. Pour les normes de conception et de style, vous pouvez également faire référence aux consignes de style Open Source. Enfin, le document finalisé sera mis en forme et publié à l'aide de WordPress.
Tableau des composants:
Voici une liste exhaustive des composants pouvant être implémentés dans le guide de style. Consignes concernant les documents : accessibilité, structure des documents, codage, sources externes, faits, polices, audience mondiale, inclusivité, légalité, accessibilité multiplate-forme, non ambiguïté, absence de revendications excessives, mise en page, langage politiquement correct, protocoles, sécurité, structure des phrases, écriture concise, ton et style, impartialité
Langue et grammaire : abréviations et acronymes, affirmation et négation, articles, majuscules, clauses, discours direct/indirect, première/deuxième/troisième personne, genres, glossaire, noms, préfixes et suffixes, prépositions, pronoms, référencement, argot et jargon, orthographe, termes techniques, temps, verbes, voix
Ponctuation : apostrophe, guillemets, deux-points, demi-points, virgule, ellipses, points d'exclamation, traits d'union et tirets, parenthèses, points, points d'interrogation et barres obliques
Mise en forme : résumés, introductions, 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, titres et titres, surlignage (gras, italique, souligné, barré, citation), indentation, index, liens et URL, listes, puces, numérotation, contenus multimédias (images, vidéos) et illustrations, notes, avertissements, conseils, chiffres et numéros de téléphone, polyglottes, traduction, scripts de langue, espacement, tableaux, texte, marques, droits d'auteur, brevets, citations, tutoriels et procédures, éléments d'interface utilisateur, unités de mesure
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, pop-ups et alertes, onglets, terminologie, éléments d'interface utilisateur, fenêtres
Code : CSS, HTML, JS, Markdown, MySQL, PHP, syntaxe, XML
Dictionnaire/Glossaire d'utilisation des mots - de A à Z