Le projet Wikimedia Foundation

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

Project description

1. À propos de moi

J'ai découvert les logiciels Open Source il y a quelques mois et j'ai été presque immédiatement submergé par leur étendue illimitée. J'ai eu du mal à progresser dans les projets bazillion. J'ai découvert des initiatives Open Source telles que Google Summer of Code et Outreachy. Google Season of Docs semblait intéressant et les idées de projets de la Wikimedia Foundation ont piqué ma curiosité, c'est pourquoi j'ai commencé à les étudier plus en détail.

Jusqu'à présent, mon parcours a été à la fois passionnant et déroutant, avec des moments de "Attendez, quoi ?", "Ah, je comprends !" et "Est-ce que je dois commenter ça ?". La communauté Wikimedia m'a soutenu à chaque étape. Qu'il s'agisse de modifier des pages ou de créer des extensions, j'en apprends tous les jours.

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

2. Projet

2.1. Contour

Ce projet vise à améliorer la documentation pour les rédacteurs techniques et les vidéastes potentiels de Wikimedia. Un ensemble mature de consignes de documentation technique aiderait à améliorer la documentation globale, et des références pour créer des screencasts permettraient de démontrer efficacement les fonctionnalités du logiciel. La documentation existante dans ces domaines peut être étendue pour mieux aider les nouveaux contributeurs et les contributeurs expérimenté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 documentalistes de Wikimedia :

    • Ajoutez 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 à certains genres de documents dans les suggestions et modèles 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]
    • Tester et améliorer les consignes de hiérarchisation de la documentation technique [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Concevez une stratégie de collecte de contenu pour différents types de documentation.
    • Élaborez une stratégie de communication et de collaboration pour la documentation de MediaWiki.
    • Créez une checklist que les rédacteurs peuvent utiliser pour vérifier leurs documents avant de les publier.
    • Étendre la structure de documentation pour les nouveaux rédacteurs techniques [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Rédigez 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éer un hub pour les rédacteurs techniques qui pointe vers des ressources utiles

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

    • Créez un guide rapide pour les utilisateurs sur la création d'un enregistrement d'écran général.
    • Concevez des modèles d'enregistrement d'écran spécifiques à MediaWiki pour les tutoriels et les procédures de dépannage.

  • T214522 [https://phabricator.wikimedia.org/T214522] : créer une vidéo d'introduction à Phabricator.

2.3. Objectif supplémentaire

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

3. Parrains

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

4. Discussion

Ce projet se divise en deux phases principales:

(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.

Auparavant, plusieurs initiatives ont été lancées pour améliorer la documentation de MediaWiki, avec des résultats plus ou moins satisfaisants. 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 pour les rédacteurs techniques aura un impact direct sur les documents qu'ils génèrent.

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

"Le guide de style de MediaWiki est loin d'être parfait, en particulier parce qu'il s'appuie trop sur des références externes sans mettre en avant 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 se retrouvent sans ressources fiables et de qualité pour effectuer leur travail, ce qui les empêche d'identifier une audience cible et un style d'écriture approprié. Les utilisateurs, en particulier les nouveaux utilisateurs, peuvent avoir des difficultés à comprendre les nouveaux concepts et processus."

T197006 [https://phabricator.wikimedia.org/T197006] met également en lumière certains aspects de la documentation technique qui doivent être améliorés. Il est clair que Documentation/Style_guide est le point de départ.

Une fois que nous aurons un meilleur guide de style, la prochaine série de documents est prévue pour guider les rédacteurs techniques à travers les différentes étapes de la rédaction technique. Les documents doivent être adaptés aux débutants, tout en fournissant toutes les informations nécessaires aux rédacteurs.

L'étape de préparation est peut-être la plus importante, car elle jette les bases sur lesquelles le document est construit. Pour aider les rédacteurs techniques à passer à cette étape, des documents de référence sont développés. Ils décrivent des méthodes efficaces pour collecter des informations pertinentes et des conseils pour structurer ces informations à l'aide de modèles.

Vient ensuite l'étape de la rédaction. Les rédacteurs reçoivent des exemples de bons travaux pour que la barre soit automatiquement placée très haut. De plus, une checklist est créée avec un ensemble de critères de base que chaque document doit respecter. Cela aidera les rédacteurs à examiner leurs documents avant de les publier.

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

Enfin, un document permettant de comprendre le processus de gestion et de maintenance de la documentation, intitulé "Priorisation de la documentation technique", est testé et amélioré.

À la fin de cette phase, un centre de guides, de ressources, d'exemples, de suggestions et de modèles de rédaction technique sera créé 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 concerne les graphiques est de 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 textuels uniquement, il est souvent impossible de recréer une série d'actions lorsque les menus et le libellé de l'application changent, car nous manquons de tous les repères que nous utilisons normalement.

Le meilleur moyen d'apprendre est peut-être de se trouver à côté d'un expert. Les enregistrements d'écran se situent entre les graphiques statiques et la présence d'un expert à portée de main. Nous obtenons une démonstration visuelle et animée avec une voix amicale. Nous pouvons également afficher des annotations textuelles à l'écran et des animations. Les enregistrements d'écran présentent un avantage par rapport aux experts : ils peuvent être rejoués à volonté, à chaque heure de chaque jour.

Nous pouvons également ajouter des sous-titres traduits à une capture d'écran pour qu'elle soit accessible aux personnes qui ne parlent pas la langue d'origine ou remplacer la piste audio par d'autres langues."

Dans l'extrait ci-dessus tiré de ""The Screencasting Handbook"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald explique l'importance des screencasts. Il 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 documents, disposer d'un modèle standard pour les enregistrements d'écran favorise l'uniformité, ce qui améliore l'expérience utilisateur. Il fournit également aux vidéastes potentiels un cadre pour se lancer. C'est pourquoi nous avons développé un guide rapide de l'utilisateur, suivi de modèles pour créer des vidéos d'introduction et des didacticiels. Les documents incluent des indications sur la profondeur des concepts à aborder et quelques idées d'enregistrements d'écran pour MediaWiki.

Le meilleur moyen de tester le modèle ci-dessus et de vous préparer à l'objectif étiré est de créer une capture d'écran à l'aide des outils et des modèles. Une vidéo d'introduction à Phabricator est donc créée, qui couvre les principes de base de l'utilisation de Phabricator. Ce processus met également en évidence les points à discuter.

Enfin, la source de référence centrale des vidéastes de Wikimedia, WikiProject Screencast, a été examinée et mise à jour.

5. Calendrier provisoire

Période de consolidation de la communauté (1er août au 1er septembre)

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

  • Discutez des points suivants:

    • Fréquence d'examen des tâches.
    • Partagez des plannings et définissez un workflow hebdomadaire/quotidien.
    • Outils et ressources pouvant être utilisés
    • Rapports sur les projets hebdomadaires et quotidiens.

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

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

Semaine 1 (2-8 septembre)

  • Améliorez la documentation/le guide de style:

    • L'objectif principal est d'illustrer les bonnes pratiques et les normes sur MediaWiki.
    • Incluez des exemples de bonnes pratiques et améliorez la visibilité des pages associées.

  • Améliorer le guide pour les nouveaux rédacteurs techniques:

    • Développez la structure de la documentation.

Semaine 2 (9-15 septembre)

  • Travaillez sur la priorisation de la documentation technique:

    • Évaluer le tableau de travail de la documentation ; trouver des exemples de bonnes descriptions des tâches et de hiérarchisation 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 pour vous aider à examiner la documentation technique avant de la publier.
    • Des moyens de collecter efficacement du contenu pour différents genres de documentation.

Semaine 4 (23 – 29 septembre)

  • Ajoutez des informations sur la rédaction dans les genres MediaWiki les plus courants aux modèles et suggestions de documentation technique:

    • Documentez les bonnes pratiques sur MediaWiki pour rédiger des guides utilisateur, des guides de démarrage rapide, des fichiers README, des notes de version et des tutoriels.

  • 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 d'intégration des nouveaux collaborateurs:

    • Mise à jour de la page: Tâches de documentation technique pour les hackathons. (À faire: ajoutez des tâches appropriées à cette page tout au long de la durée du projet)

  • Créer un hub pour les rédacteurs techniques

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

Semaine 6 (7-13 octobre)

  • Créez les documents suivants sur la réalisation de vidéos pour MediaWiki:

    • Guide rapide pour créer un enregistrement d'écran général, qui renvoie au projet d'enregistrement d'écran.
    • Modèles pour: tutoriels sur l'utilisation d'un logiciel/d'un outil ; tutoriels sur le développement de nouveaux outils.

  • Crée une liste d'idées d'enregistrements d'écran pour MediaWiki.

Semaine 7 (14-20 octobre)

  • Regardez la vidéo "Phabricator : présentation" :

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

Semaine 8 (21 – 27 octobre)

  • Publiez la vidéo "Phabricator : présentation" :

    • 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 à l'amélioration de la documentation du projet Enregistreur d'écran:

    • Examinez la structure et discutez des modifications à apporter, le cas échéant.
    • Examinez les logiciels mentionnés.
    • Recherchez et mettez à jour la liste des logiciels.

Semaine 10 (4-10 novembre)

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

    • Évaluez et améliorez le tutoriel et les scripts.
    • Consultez la galerie de vidéos.

Semaine 11 (11-17 novembre)

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

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

Semaine 12 (18-24 novembre)

  • Travaillez sur les tâches en attente.

  • Rédigez le rapport final:

    • Consultez les rapports bimensuels/quotidiens et collectez 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)

  • Envoyez le rapport final et le mentorat évalué.

6. Suivi de la progression

Je communiquerai quotidiennement l'avancement de mon projet à mes mentors via Zulip. La communauté Wikimedia peut suivre ma progression via Phabricator ou les rapports sur le projet bimensuels.

7. Autres engagements

Je suis étudiant à temps plein, et mon semestre d'automne coïncide avec la période de la saison de Google Docs. 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 prévois également d'assister à ma première conférence publique, PyCon India, du 12 au 15 octobre, grâce à l'emplacement favorable de cette année. Je pense que ce serait une excellente occasion de rencontrer de nouvelles personnes et d'avoir des conversations constructives.

Pour gérer ces engagements, le calendrier provisoire contient des tâches moins importantes dans les semaines correspondantes. Je ne compte pas obtenir plus de 20 crédits de base au cours du semestre d'automne afin de disposer de suffisamment de temps pour développer la documentation. (Un étudiant régulier obtient en moyenne 25 crédits par semestre)