Projet VideoLAN

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:

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 (3 mois)

Project description

EXTRAIT

Une 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, des conseils et astuces et également à résoudre les problèmes courants rencontrés lors de l’utilisation du logiciel. Cela permet également de réduire les coûts d'assistance et fait partie de l'identité d'entreprise du produit: une documentation utilisateur de qualité est un signe de l'intégrité du produit, de l'équipe de développeurs.

Sans une bonne documentation utilisateur, un utilisateur peut ne pas savoir comment faire les choses ci-dessus de manière efficace. Les documentations utilisateur peuvent jouer un rôle central dans le succès d'un produit, car une excellente communication est et sera toujours au cœur de toute entreprise ou tout produit et une excellente documentation prend simplement cette communication et la place 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 le lecteur multimédia VLC est téléchargé environ 23 millions de fois par mois à partir du site Web principal. Cela montre que de nombreuses personnes à travers le monde utilisent VLC Media Player et pourraient vouloir lire sa documentation pour savoir comment l'utiliser. Cependant, la documentation utilisateur du lecteur multimédia VLC est actuellement obsolète et incomplète (dernière modification le 28 octobre 2015). La communauté VideoLAN souhaite se servir de ce projet pour améliorer sa documentation afin de permettre aux utilisateurs finaux de bénéficier d'une expérience fluide avec le lecteur multimédia VLC.

ÉTAT ACTUEL

Actuellement, la documentation utilisateur est disponible sur une page wiki. Il est obsolète, incomplet, difficile à parcourir ou difficile à trouver, ne couvre pas les informations sur la version actuelle du lecteur multimédia et ne peut être traduit qu'en allemand, ce qui cause un revers majeur pour les personnes qui ne savent pas lire la langue anglaise.

POURQUOI LA DOCUMENTATION UTILISATEUR PROPOSÉE EST-ELLE AMÉLIORÉE PAR RAPPORT À LA DOCUMENTATION ACTUELLE ?

La documentation utilisateur proposée sera structurée de manière à améliorer et à assurer l'efficacité, la cohérence et la tranquillité d'esprit de l'utilisateur final. Il contiendra des guides écrits et les images associées, ainsi que des instructions et des explications sur l'utilisation de chaque fonctionnalité du lecteur multimédia VLC. Ces documents seront à jour, faciles à parcourir, compréhensibles et traduisibles 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 serait migrée à des fins d'amélioration. Il a partagé deux liens vers un dépôt Gitlab du fichier source écrit avec Sphinx et la documentation principale hébergée sur Read the Docs. Il m'a dit qu'ils s'attendaient à ce que la nouvelle documentation soit similaire. J'ai beaucoup effectué de recherches sur ces outils pour mieux comprendre leur fonctionnement.

Sphinx

Sphinx est une solution robuste et mature de documentation logicielle. Il inclut un certain nombre de fonctionnalités attendues des rédacteurs, telles que la publication à une source unique, la réutilisation du contenu par le biais d'inclusions, les inclusions conditionnelles basées sur le type de contenu et les balises, plusieurs thèmes HTML réservés aux adultes qui offrent une excellente expérience utilisateur sur mobile et ordinateur, le référencement pour plusieurs pages, documents et projets, compatibilité avec les index et les glossaires, et compatibilité avec l'internationalisation. Il utilise également reStructuredText comme langage de balisage, et bon nombre de ses points forts proviennent de la puissance et de la simplicité de reStructuredText, ainsi que de sa capacité à traduire la documentation.

Consultez la documentation

Google Docs simplifie la documentation logicielle en automatisant la création, la gestion des versions et l'hébergement de vos documents pour vous. Il n'est jamais désynchronisé. Autrement dit, à chaque fois que vous transférez du code vers votre système de contrôle de version préféré, qu'il s'agisse de Git, Mercurial, Bazar 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 créer plusieurs versions de vos documents. Il est donc aussi facile de disposer d'une version 1.0 et d'une version 2.0 que d'une branche ou d'une balise distinctes dans votre système de contrôle des versions. Read the Docs est un outil sans frais et Open Source qui héberge la documentation relative à près de 100 000 projets Open Source, petits et grands, dans presque tous les langages humains et informatiques.

VERDICT

Sphinx est un outil incroyablement puissant et Read the Docs s'appuie sur pour héberger la documentation Sphinx. Vos documents restent ainsi à jour sur toutes les versions. Ensemble, ils constituent un excellent ensemble d'outils que les développeurs et les rédacteurs techniques peuvent utiliser pour créer une documentation utilisateur idéale pour les utilisateurs finaux.

Sphinx prend en charge la traduction de la documentation dans plusieurs langues. Il prend en charge le contrôle des versions qui sera utilisé pour gérer la documentation. Contrairement au wiki actuel, où n'importe qui peut modifier les informations sans y ajouter les bonnes informations, ce système de contrôle des versions veille à ce que toutes les modifications soient examinées avant d'être fusionnées avec le référentiel principal. Le contrôle des versions contribuera également à accroître la contribution de la documentation Open Source au projet, car les utilisateurs pourront créer des problèmes, ouvrir des demandes d'extraction, etc. Sphinx et lire les documents sont utilisés par une liste d'autres grandes et communautés telles que ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, etc. C'est un excellent outil à utiliser pour la nouvelle documentation utilisateur VLC.

En plus de découvrir ces outils, j'ai créé un exemple de base. Voici le lien https://gitlab.com/Didicodes/demo-vlc-user-documentation de mon dépôt Gitlab, et 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éé la structure de la documentation utilisateur VLC disponible ici : https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Avant que la mise en œuvre 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

• Restructurez la documentation.
• Mettez à jour la documentation pour qu'elle corresponde aux versions modernes de VLC.
• Migrez la documentation utilisateur vers Gitlab à l'aide de Sphinx et ReadtheDocs.
• Supprimez les images et les informations obsolètes.
• Réécrire la documentation utilisateur pour la rendre plus facile à comprendre.
• Configurez-la pour la traduction à l'aide de l'internationalisation Sphinx.
• Encouragez la communauté de la documentation 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 tout leur potentiel lorsque vous avez également la capacité d'éclairer les autres à ce sujet par l'écriture. Personnellement, j'ai toujours été fascinée par les efforts entrepris par la communauté VideoLAN pour créer des solutions logicielles sans frais pour le multimédia. Quand j'étais enfant, le lecteur multimédia VLC était toujours le logiciel que j'utilisais pour écouter de la musique ou regarder un film. Il était très bruyant et contenait de nombreuses fonctionnalités. Ce sera un honneur de travailler avec la communauté qui a contribué à rendre mon enfance extraordinaire.

POURQUOI SUIS-JE LA BONNE PERSONNE POUR CE PROJET ?

Je pense être la bonne personne pour ce projet car:

• J'ai de l'expérience dans l'amélioration de la documentation des organisations et je peux utiliser n'importe quel système de contrôle des versions. Par conséquent, exécuter des commandes sur Gitab ne sera pas un problème. De plus, ce qui me motive, c'est de travailler sur des projets qui créent de la valeur pour les gens.
• Je crois que si vous voulez que quelqu'un fasse quelque chose de la manière la plus efficace possible, vous le documentez. En documentant vos processus, vous garantissez l'efficacité, la cohérence et la tranquillité d'esprit de toutes les personnes concernées.
• Je connais les besoins des utilisateurs de VLC, car j’en fais partie. Vous pourrez ainsi rédiger la documentation de sorte que tous les utilisateurs à travers le monde puissent en comprendre un aperçu.