Projet VideoLAN

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:

VideoLAN

Rédacteur technique:

Edidiong Anny Asikpo

Nom du projet:

Moderniser (réécrire) la documentation utilisateur de VLC

Durée du projet:

Durée standard (trois mois)

Project description

ABSTRACT

La documentation utilisateur est conçue pour aider les utilisateurs finaux à utiliser un produit ou un service. Une bonne documentation utilisateur est très importante car elle offre aux utilisateurs un moyen d'apprendre à utiliser un logiciel, ses fonctionnalités, ses conseils, ses astuces et également de résoudre les problèmes courants rencontrés lors de l'utilisation du logiciel. Elle réduit également les coûts de support et fait partie de l'identité de l'entreprise du produit: une bonne documentation utilisateur est un signe de bonne santé du produit et de l'équipe de développement.

Sans une bonne documentation utilisateur, un utilisateur peut ne pas savoir comment effectuer les tâches ci-dessus de manière efficace. La documentation utilisateur peut jouer un rôle essentiel dans la réussite d'un produit, car une bonne communication est et restera toujours au cœur de toute entreprise ou de tout produit. Une bonne documentation ne fait que prendre cette communication et la placer dans un cadre gérable auquel tout le monde peut accéder pour réussir.

Au moment de la rédaction de cet article, la documentation utilisateur de VLC a été consultée 4 634 065 fois et VLC Media Player est téléchargé environ 23 millions de fois par mois sur le site Web principal. Cela montre que de nombreuses personnes dans le monde entier utilisent VLC Media Player et peuvent souhaiter lire sa documentation utilisateur pour savoir comment l'utiliser. Cependant, la documentation utilisateur du lecteur multimédia VLC est actuellement obsolète et incomplète (elle a été modifiée pour la dernière fois le 28 octobre 2015). La communauté VideoLAN souhaite utiliser ce projet pour améliorer sa documentation utilisateur afin de permettre aux utilisateurs finaux de profiter d'une expérience fluide lorsqu'ils utilisent le lecteur multimédia VLC.

ÉTAT ACTUEL

Actuellement, la documentation utilisateur est disponible sur une page Wiki. Il est obsolète, incomplet, difficile à parcourir et à trouver des informations, ne couvre pas la version actuelle du lecteur multimédia et ne peut être traduit qu'en allemand, ce qui constitue un obstacle majeur pour les personnes qui ne lisent pas l'anglais.

POURQUOI LA DOCUMENTATION UTILISATEUR QUE JE PROPOSE EST-ELLE UNE AMÉLIORATION DE LA DOCUMENTATION ACTUELLE ?

La documentation utilisateur proposée sera structurée pour améliorer et garantir l'efficacité, la cohérence et la tranquillité d'esprit de l'utilisateur final. Il contiendra des guides écrits et les images associées, des instructions et des explications sur l'utilisation de chaque fonctionnalité du lecteur multimédia VLC, et sera à jour, facile à parcourir, compréhensible et traduisible dans au moins cinq langues principales.

Mentors: Jean-Baptiste, Alex, Simon

ANALYSE

Jean-Baptiste et moi avons discuté du nouvel environnement vers lequel la documentation utilisateur actuelle allait être migrée afin d'être améliorée. Il nous a communiqué deux liens qui montraient un dépôt Gitlab du fichier source écrit avec Sphinx et la principale documentation hébergée sur Read the Docs. Il nous a dit qu'il s'attendait à ce que la nouvelle documentation ressemble à celle-ci. J'ai beaucoup étudié ces outils pour mieux comprendre leur fonctionnement.

Sphinx

Sphinx est une solution robuste et mature pour la documentation logicielle. Il inclut un certain nombre de fonctionnalités attendues par les rédacteurs, telles que la publication à partir d'une seule source, la réutilisation de contenu via des inclusions, des inclusions conditionnelles basées sur le type de contenu et les balises, plusieurs thèmes HTML matures qui offrent une expérience utilisateur optimale sur mobile et sur ordinateur, le référencement entre les pages, les documents et les projets, la prise en charge de l'index et du glossaire, ainsi que la prise en charge de l'internationalisation. Il utilise également reStructuredText comme langage de balisage. De nombreuses de ses forces proviennent de la puissance et de la simplicité de reStructuredText, ainsi que de sa capacité à traduire la documentation.

Consultez la documentation

Read the Docs simplifie la documentation logicielle en automatisant la création, la gestion des versions et l'hébergement de vos documents. Il ne se désynchronise jamais. Autrement dit, chaque fois que vous transférez du code vers votre système de contrôle des versions préféré, qu'il s'agisse de Git, Mercurial, Bazaar ou Subversion, Read the Docs crée automatiquement vos documents afin que votre code et votre documentation soient toujours à jour. Il existe plusieurs versions. Read the Docs peut héberger et compiler plusieurs versions de vos documents. Il est donc aussi simple d'avoir une version 1.0 et une version 2.0 de vos documents que d'avoir une branche ou une balise distincte dans votre système de contrôle des versions. Read the Docs est un projet Open Source et héberge la documentation de près de 100 000 projets Open Source, petits et grands, dans presque toutes les langues humaines et informatiques.

VERDICT

Sphinx est un outil incroyablement puissant. Read the Docs s'appuie sur lui pour héberger la documentation Sphinx et la mettre à jour à chaque version. Ensemble, ils constituent un excellent ensemble d'outils que les développeurs et les rédacteurs techniques peuvent utiliser pour créer la documentation utilisateur la plus adaptée aux utilisateurs finaux.

Sphinx permet de traduire la documentation dans plusieurs langues. Il est compatible avec le contrôle des versions, qui sera utilisé pour gérer la documentation. Contrairement au wiki actuel, où n'importe qui peut modifier sans ajouter les bonnes informations, ce système de contrôle des versions garantit que toutes les modifications sont d'abord examinées avant d'être fusionnées avec le référentiel principal. Le contrôle des versions permettra également d'augmenter la contribution Open Source à la documentation, car les utilisateurs pourront créer des problèmes, ouvrir des requêtes pull, etc. Sphinx et Read the Docs sont utilisés par de nombreuses autres communautés telles que ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, etc. et constituent un excellent outil pour la nouvelle documentation utilisateur de VLC.

Je n'ai pas seulement lu des informations sur ces outils, j'ai également créé un exemple de base. Voici le lien: https://gitlab.com/Didicodes/demo-vlc-user-documentation vers mon dépôt Gitlab. La version hébergée sur readthedocs est disponible ici: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.

STRUCTURE DE LA DOCUMENTATION PROPOSÉE

J'ai créé une structure pour la documentation utilisateur de VLC, que vous pouvez consulter ici : https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Avant que l'implémentation de cette nouvelle structure ne commence, elle doit être approuvée par les mentors. Cela signifie que la structure est susceptible de changer après avoir été examinée par les mentors.

OBJECTIFS DU PROJET

• Restructurer la documentation.
• Mise à jour de la documentation pour qu'elle corresponde aux versions modernes de VLC.
• Migrez la documentation utilisateur vers Gitlab à l'aide de Sphinx et de ReadtheDocs.
• Supprimez les images et informations obsolètes.
• Réécrivez la documentation utilisateur pour la rendre plus facile à comprendre.
• Configurez-le pour la traduction à l'aide de l'internationalisation Sphinx.
• Faites en sorte que la documentation soit gérée par la communauté afin que les utilisateurs puissent signaler ou résoudre les problèmes rencontrés lors de la lecture de la documentation.

POURQUOI CE PROJET ?

J'ai toujours eu la conviction que l'écriture de code, la résolution de problèmes et la création de logiciels atteignent leur plein potentiel lorsque l'on est également capable d'informer les autres à ce sujet par l'écriture. Personnellement, j'ai toujours été fasciné par les efforts entrepris par la communauté VideoLAN pour créer des solutions logicielles sans frais pour le multimédia. Lorsque j'étais enfant, j'utilisais toujours VLC Media Player pour écouter de la musique ou regarder un film, car il était très fort et proposait de nombreuses fonctionnalités. Ce sera un honneur de travailler avec la communauté qui a contribué à rendre mon enfance géniale.

POURQUOI SUIS-JE LA BONNE PERSONNE POUR CE PROJET ?

Je pense être la bonne personne pour ce projet pour les raisons suivantes:

• J'ai déjà amélioré la documentation d'organisations et je peux utiliser n'importe quel système de contrôle des versions. L'exécution de commandes sur GitHub ne sera donc pas un problème. De plus, ce qui me motive est de travailler sur des projets qui créent de la valeur pour les gens.
• Je pense que si vous voulez que quelqu'un fasse quelque chose de la manière la plus efficace possible, vous devez le documenter. En documentant vos processus, vous assurez l'efficacité, la cohérence et la tranquillité d'esprit de toutes les personnes impliquées.
• Je connais les besoins des utilisateurs de VLC, car je suis l'un d'eux. Vous pourrez ainsi rédiger la documentation de manière à ce que tous les utilisateurs du monde entier la comprennent au premier coup d'œil.