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 documentation utilisateur de qualité est très importante, car elle permet aux utilisateurs d'apprendre à utiliser un logiciel, ses fonctionnalités, d'obtenir des conseils et des astuces, mais aussi de 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é indique que le produit est opérationnel, selon 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 où nous écrivons ces lignes, 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. Nous vous conseillons donc de lire sa documentation pour savoir comment utiliser le lecteur multimédia. Toutefois, la documentation utilisateur du lecteur multimédia VLC est actuellement obsolète et incomplète (dernière modification effectuée le 28 octobre 2015). La communauté VideoLAN souhaite exploiter ce projet pour améliorer sa documentation utilisateur afin de permettre aux utilisateurs finaux de bénéficier 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 ou à 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 des difficultés majeures aux personnes qui ne savent pas lire la langue anglaise.

POURQUOI MA DOCUMENTATION UTILISATEUR CONCERNÉE EST-elle UNE AMÉLIORATION PAR RAPPORT À LA DOCUMENTATION ACTUELLE ?

La documentation utilisateur proposée sera structurée de manière à 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, ainsi que des instructions et des explications sur l'utilisation de chaque fonctionnalité du lecteur multimédia VLC. Il sera à jour, facile à parcourir, compréhensible et traduisible dans au moins cinq langues principales.

Parrains: Jean-Baptiste, Alex, Simon

ANALYSE

Avec Jean-Baptiste, nous avons discuté avec lui du nouvel environnement vers lequel la documentation utilisateur actuelle serait transféré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 s'attendait à ce que la nouvelle documentation soit semblable à celle-ci. J'ai beaucoup fait de recherches sur ces outils pour mieux comprendre comment ils fonctionnent.

Sphinx

Sphinx est une solution robuste et mature pour la documentation logicielle. Elle inclut un certain nombre de fonctionnalités attendues par les rédacteurs, comme la publication à une source unique, la réutilisation de contenu via des inclusions, des inclusions conditionnelles en fonction du type de contenu et des 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 dans 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 beaucoup 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

Cet outil simplifie la documentation des logiciels en automatisant la création, la gestion des versions et l'hébergement de vos documents pour vous. Il ne se désynchronise jamais. Ainsi, lorsque 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 d'avoir une version 1.0 et une version 2.0 de vos documents que d'avoir une branche ou une balise séparée 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 de près de 100 000 projets Open Source, petits et grands, dans presque tous les langages humain et informatiques.

VERDICT

Sphinx est un outil incroyablement puissant et Read the Docs s'appuie sur le composant pour héberger la documentation Sphinx qui maintient vos documents à jour, quelle que soit leur version. 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 parfaitement adaptée aux 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 de version 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 au projet Open Source, 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 communautés de qualité, telles que ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, etc. C'est un excellent outil à utiliser pour la nouvelle documentation utilisateur VLC.

Je ne me suis pas contenté de découvrir ces outils, j'ai également créé un échantillon de base. Voici le lien: https://gitlab.com/Didicodes/demo-vlc-user-documentation vers mon dépôt Gitlab, tandis que 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 VLC disponible à l'adresse https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Avant que 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.
• Mettez à jour la documentation pour l'adapter 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 qu'elle soit plus facile à comprendre.
• Configurez-la pour la traduction à l'aide de l'internationalisation Sphinx.
• Animez 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 été convaincu que l'écriture de code, la résolution de problèmes et la création de logiciels atteignent tout leur potentiel lorsque l'on peut également en éclairer les autres par le biais de 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. Dans mon enfance, le lecteur multimédia VLC était toujours le logiciel que j'utilisais pour écouter de la musique ou regarder un film, car il était très bruyant et était composé 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. Cela permettra de rédiger la documentation de manière à ce que tous les autres utilisateurs à travers le monde comprennent au premier coup d'œil.