Le projet Wikimedia Foundation

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:
The Wikimedia Foundation
Rédacteur technique:
Pavithra Eswaramoorthy
Nom du projet:
Amélioration de la documentation pour les documentaristes techniques et les vidéastes de Wikimedia
Durée du projet:
Durée standard (3 mois)

Project description

1. À propos de moi

Il y a quelques mois, j'ai découvert le logiciel Open Source et je me suis presque immédiatement senti dépassé par son champ d'application illimité. Alors que je n'arrivais pas à me frayer un chemin dans les projets du bazillion, j'ai découvert des initiatives Open Source telles que Google Summer of Code et Google Outreach. Google Season of Docs semblait intéressant et les idées de projets de la Wikimedia Foundation ont suscité ma curiosité, alors j'ai commencé à chercher plus loin.

Jusqu'à présent, mon parcours a été tout aussi excitant et déroutant, avec des expressions du type "Attends, quoi ?", "Ahh, j'ai compris !" et "Dois-je commenter cela ?". La communauté Wikimedia nous a soutenu à chaque étape. Qu'il s'agisse de modifier des pages ou de créer des extensions, j'apprends chaque jour de nouvelles choses.

Comme prévu, le processus de candidature a servi de passerelle vers la communauté Open Source. Cette proposition s'inspire de mes propres expériences de débutant.

2. Projet

2.1. Outline

Ce projet vise à améliorer la documentation destinée aux rédacteurs techniques et aux vidéastes potentiels sur Wikimedia. Un ensemble mature de directives de documentation technique contribuerait à favoriser une meilleure documentation globale, et des références à la création d'enregistrements d'écran permettraient de faire une démonstration efficace des fonctionnalités logicielles. La documentation existante dans ces domaines peut être étendue afin de mieux aider les nouveaux contributeurs et les contributeurs chevronnés. Une approche progressive sera adoptée pour développer ce réseau de ressources pratiques.

2.2. Livrables

  • T197006 [https://phabricator.wikimedia.org/T197006] - Amélioration de la documentation pour les documentaristes de Wikimedia:

    • Ajouter des conseils et des exemples à la documentation/au guide de style [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Ajoutez des informations spécifiques à MediaWiki pour certains genres dans des modèles et des suggestions de documentation technique: guides utilisateur, tutoriels, guides de démarrage rapide, notes de version et fichiers README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Testez et améliorez les consignes de priorisation de la documentation technique. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Concevez une stratégie de collecte de contenu pour différents genres de documentation.
    • Élaborer une stratégie de communication et de collaboration pour la documentation de MediaWiki.
    • Créez une liste de contrôle permettant aux rédacteurs de consulter leurs documents avant de les publier.
    • Développez la structure de la documentation pour les nouveaux rédacteurs techniques. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Organiser une liste de tâches de documentation technique adaptées aux hackathons. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Créez un hub pour un rédacteur technique qui renvoie vers des ressources utiles.

  • Amélioration de la documentation pour les vidéastes MediaWiki:

    • Créez un guide utilisateur rapide pour réaliser un enregistrement d'écran général.
    • Concevez des modèles d'enregistrement d'écran spécifiques à MediaWiki pour des présentations et des tutoriels.

  • T214522 [https://phabricator.wikimedia.org/T214522] – Créez un enregistrement d'écran "Introduction to Phabricator".

2.3. Objectif étirement

  • Revérifiez le contenu et mettez à jour la documentation de WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Parrains

Zulip sera le principal moyen de communication avec mes mentors. Les canaux et l'adresse e-mail IRC de Wikimedia seront utilisés pour les discussions avec la communauté. Les discussions sur des tâches spécifiques auront lieu dans la section des commentaires des tâches de Phabricator.

4. Discussion

Dans l'ensemble, ce projet comporte deux phases:

(i) Améliorer les ressources existantes pour les rédacteurs techniques de Wikimedia.

(ii) Créer des modèles utiles pour les vidéastes potentiels.

(i) Améliorer les ressources existantes pour les rédacteurs techniques de Wikimedia.

Par le passé, plusieurs initiatives ont été lancées pour améliorer la documentation de MediaWiki, avec plus ou moins de succès. dont les suivants :

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Ces efforts nous permettent de comprendre qu'un meilleur ensemble de ressources destinées aux rédacteurs techniques aura un impact direct sur les documents qu'ils génèrent.

Voici un extrait du rapport bihebdomadaire d'Anna e só, une stagiaire de 2018 dans l'équipe d'Outreachy https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

"Le guide de style de MediaWiki est loin d'être parfait, d'autant qu'il repose sur trop de références externes sans mettre en évidence les pratiques qu'il considère comme les meilleures. Malheureusement, ce problème ne se limite pas à MediaWiki, car il apparaît dans d'autres documents, comme les bonnes pratiques de traduction. Les rédacteurs finissent par ne pas avoir de bonnes ressources fiables pour faire leur travail, ce qui entraîne des difficultés à établir une audience cible et un style d’écriture approprié. De plus, les utilisateurs, en particulier les nouveaux utilisateurs, peuvent rencontrer des problèmes pour comprendre les nouveaux concepts et processus."

T197006 [https://phabricator.wikimedia.org/T197006] met également en lumière certains domaines de la documentation de rédaction technique qui doivent être améliorés. Vous devez clairement commencer par Documentation/Style_guide.

Une fois que nous disposerons d'un meilleur guide de style, la prochaine série de documents devrait guider les rédacteurs techniques à travers les différentes étapes de la rédaction technique. Les documents doivent être adaptés aux débutants et fournir en même temps toutes les informations nécessaires aux rédacteurs.

La phase de préparation est sans doute la plus importante, car elle constitue la base sur laquelle le document est rédigé. Pour aider les rédacteurs techniques à traverser cette étape, des documents de référence sont développés décrivant quelques moyens efficaces de recueillir des informations pertinentes et des conseils sur la structuration de ces informations à l'aide de modèles.

Vient ensuite l'étape d'écriture. Les rédacteurs reçoivent des exemples de travail réussi pour mettre automatiquement la barre plus haut. De plus, une liste de contrôle est créée avec un ensemble de critères de base que chaque document doit respecter, ce qui aidera les rédacteurs à revoir leurs documents avant de les publier.

Même avec ces documents, les nouveaux rédacteurs techniques auront besoin d'une aide supplémentaire, et nous devons les leur donner. Le guide destiné aux nouveaux rédacteurs techniques est affiné et une liste de tâches adaptées aux hackathons est organisée en fonction du niveau de difficulté.

Enfin, un document visant à comprendre le processus de gestion et de maintenance de la documentation ("Hiérarchisation de la documentation technique") est testé et amélioré.

À la fin de cette phase, un hub de guides de rédaction technique, de ressources, d'exemples, de suggestions et de modèles sera établi pour soutenir le guide de style de la documentation.

(ii) Créer des modèles utiles pour les vidéastes potentiels.

"L'un des moyens les plus difficiles d'apprendre tout ce qui implique des graphiques consiste à lire du texte brut. Imaginez également ce qui se passe si votre manuel fait référence à la mauvaise version du logiciel. Avec les manuels au format texte, il devient souvent impossible de recréer une série d'actions lorsque les menus et la formulation de l'application changent, car nous n'avons pas tous les indicateurs que nous utiliserions normalement.

La meilleure façon d'apprendre est peut-être de rencontrer un expert à côté de vous. Les enregistrements d'écran se situent entre des images statiques et l'aide d'un expert à portée de main. Nous proposons une démo visuelle et émouvante avec une voix amicale, ainsi que des annotations textuelles à l'écran et des animations. L'avantage des enregistrements d'écran par rapport à un expert est qu'ils peuvent être visionnés à volonté toutes les heures de la journée.

Nous pouvons aussi ajouter des sous-titres traduits à un enregistrement d'écran pour qu'ils puissent être vus par des locuteurs non natifs ou remplacer la piste audio par d'autres langues."

Dans l'extrait ci-dessus tiré du "The Screencasting Handbook" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald explique l'importance des enregistrements d'écran. Cela peut être particulièrement utile pour les tutoriels sur la configuration de l'environnement de développement MediaWiki, l'écriture d'extensions, l'utilisation de Gerrit, etc.

Comme pour les modèles de documents, disposer d'un modèle standard pour les enregistrements d'écran favorise l'uniformité, améliorant ainsi l'expérience de l'utilisateur. Elle fournit également aux vidéastes potentiels un cadre pour se lancer. C'est pourquoi nous avons créé un guide d'utilisation rapide suivi de modèles pour créer des vidéos d'introduction et des didacticiels vidéo. Elle contient des indications sur la profondeur des concepts à aborder et quelques idées d'enregistrement d'écran pour MediaWiki.

La meilleure façon de tester le modèle ci-dessus et de se préparer à l'objectif ambitieux consiste à créer un enregistrement d'écran à l'aide des outils et des modèles. C'est pourquoi un enregistrement d'écran "Introduction to Phabricator" (Présentation de Phabricator) couvre les bases de l'utilisation de Phabricator. Ce processus mettra également en évidence les domaines qui nécessitent une discussion.

Enfin, la source centrale de référence pour les vidéastes de Wikimedia : l'Enregistreur d'écran WikiProject, est revu et mis à jour.

5. Calendrier provisoire

Période de cohésion de la communauté (1er août - 1er septembre)

  • Analyser le projet en détail avec mes mentors.

  • Discuter des points suivants:

    • La fréquence à laquelle les tâches doivent être examinées.
    • Partagez des plannings et établissez un flux de travail hebdomadaire/quotidien.
    • Outils et ressources utilisables.
    • Des rapports de projet bihebdomadaires et quotidiens.

  • Créez les tâches et sous-tâches requises sur Phabricator.

  • Créer des brouillons pour compenser les engagements personnels lors de la phase de développement du document.

Semaine 1 (2 - 8 septembre)

  • Amélioration de la documentation/du style_guide:

    • Déplacez l'objet principal pour illustrer les meilleures pratiques et normes sur MediaWiki.
    • Incluez des exemples de bon travail et améliorez la visibilité des pages associées.

  • Amélioration du guide destiné aux nouveaux rédacteurs techniques:

    • Développez la structure de la documentation.

Semaine 2 (9 – 15 septembre)

  • Hiérarchiser la documentation technique:

    • Évaluez le tableau de travail de documentation ; trouvez des exemples de bonnes descriptions et de hiérarchisations des tâches.
    • Étudiez les tendances et notez les difficultés courantes.
    • Utilisez les informations et les exemples pour documenter les normes de priorisation.

Semaine 3 (16 - 22 septembre)

  • Créez la documentation supplémentaire suivante pour les rédacteurs techniques:

    • Checklist permettant de consulter la documentation technique avant publication
    • Des moyens de collecter efficacement du contenu pour différents genres de documentation.

Semaine 4 (23 - 29 septembre)

  • Ajoutez des informations sur l'écriture dans les genres MediaWiki les plus courants aux modèles et suggestions de documentation technique:

    • Documentez les meilleures pratiques sur MediaWiki pour la rédaction de guides utilisateur, de guides de démarrage rapide, de fichiers README, de notes de version et de guides pratiques.

  • Ajoutez des instructions pour améliorer la maturité de la communication technique. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Semaine 5 (30 septembre - 6 octobre)

  • Amélioration de la documentation pour l'intégration de nouveaux collaborateurs:

    • Mettre à jour la page: tâches de documentation technique pour les hackathons (À faire: ajoutez les tâches appropriées à cette page tout au long de la période du projet)

  • Construire un centre de rédaction technique

    • Créez une page de destination avec des liens vers des pages et des ressources utiles.
    • Ajoutez les liens nécessaires vers les pages nouvelles et existantes pour faciliter la navigation entre elles.

Semaine 6 (7 - 13 octobre)

  • Créez les documents suivants sur la création de vidéos pour MediaWiki:

    • Guide de l'utilisateur rapide sur la création d'un enregistrement d'écran général pointant vers le projet Enregistreur d'écran.
    • Modèles pour: tutoriels sur l'utilisation d'un logiciel/outil ; tutoriels sur le développement de nouveaux outils.

  • Créer une liste d'idées d'enregistrement d'écran pour MediaWiki

Semaine 7 (14-20 octobre)

  • Travaillez sur la vidéo "Présentation de Phabricator" :

    • Utilisez le modèle (créé la semaine précédente) pour rédiger un script.
    • Estimez l'efficacité du modèle et améliorez-le si nécessaire.
    • Recueillez des commentaires et finalisez le brouillon.

Semaine 8 (21-27 octobre)

  • Publiez la vidéo "Introduction to Phabricator" (Présentation de Phabricator) :

    • Sélectionnez et installez le logiciel.
    • Configurez l'environnement et créez l'enregistrement d'écran.
    • Notez les problèmes rencontrés et les solutions.

Semaine 9 (28 octobre - 3 novembre)

  • Travaillez à améliorer la documentation du projet Enregistreur d'écran:

    • Examinez la structure et discutez de tout changement nécessaire.
    • Examinez les logiciels mentionnés.
    • Faire des recherches et mettre à jour la liste des logiciels.

Semaine 10 (4 - 10 novembre)

  • Continuez à améliorer la documentation du projet Enregistreur d'écran:

    • Évaluer et améliorer le tutoriel et les scripts
    • Parcourez la galerie des enregistrements d'écran.

Semaine 11 (11 - 17 novembre)

  • Terminez le travail sur la documentation du projet Enregistreur d'écran:

    • Recherchez des vidéos plus récentes et ajoutez-les à la galerie.
    • Apportez les modifications structurelles nécessaires.

Semaine 12 (18 - 24 novembre)

  • Travaillez sur les tâches en attente.

  • Rédiger le rapport final:

    • Consulter les rapports bihebdomadaires/quotidiens et recueillir les informations requises.
    • Planifiez la structure du rapport et rédigez un brouillon.
    • Améliorer et finaliser le brouillon en fonction des commentaires du mentor.

Semaine 13 (25 - 29 novembre)

  • Soumettez le rapport final et l’évaluation du mentor.

6. Suivi de la progression

Des informations quotidiennes sur les progrès accomplis seront communiquées à mes mentors via Zulip. La communauté Wikimedia peut suivre mes progrès grâce à Phabricator ou aux rapports de projet bimensuels.

7. Autres engagements

Je suis étudiant à temps plein à l'université et mon semestre universitaire d'automne chevauche la chronologie de la saison des documents. Par conséquent, mes engagements incluent les examens universitaires.

Premier examen interne: du 18 au 24 août

Deuxième examen interne: du 29 septembre au 6 octobre

Examen de fin de semestre: du 11 au 30 novembre

Je compte également assister à ma première conférence publique, PyCon India, du 12 au 15 octobre grâce à son emplacement favorable cette année. Je pense que ce serait une excellente occasion de rencontrer de nouvelles personnes et d’avoir des conversations instructives.

Pour gérer ces engagements, le calendrier provisoire contient des tâches moins lourdes dans les semaines correspondantes. J'ai l'intention de ne pas obtenir plus de 20 crédits de base au cours du semestre d'automne afin d'avoir suffisamment de temps pour élaborer des documents. (Un élève ordinaire obtient en moyenne 25 crédits par semestre)