Projet VLC

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:

VLC

Rédacteur technique:

Avii

Nom du projet:

Créer la documentation utilisateur de VLC pour un port mobile (Android)

Durée du projet:

Durée standard (trois mois)

Project description

ABSTRACT

La documentation utilisateur sert de système d'assistance statique pour aider les utilisateurs finaux. Il fournit des informations techniques et non techniques sur un produit ou un service. Elle aide les utilisateurs à apprendre à utiliser un logiciel ou un service. Tout le monde ne souhaite pas contacter l'assistance ni attendre une réponse par e-mail s'il n'a besoin que d'un petit conseil ou d'une astuce. La documentation utilisateur fait exactement cela. Cela permet également de réduire les coûts d'assistance et de refléter l'état de santé du produit et de l'équipe de développement.

VLC pour Android a été téléchargé plus de 100 millions de fois sur le Google Play Store. VLC fournit de nombreuses fonctionnalités pour ses ports mobiles, allant de la lecture audio-vidéo au flux réseau. Souvent, les utilisateurs souhaitent utiliser ces fonctionnalités formidables, mais ce n'est pas possible. Rechercher un blog ou une vidéo au hasard pour cela demande beaucoup de temps et de patience, mais les informations obtenues ne sont pas authentiques. Actuellement, VLC héberge la documentation utilisateur de VLC pour Android sur la page Wiki et fournit une description limitée ou aucune de ces fonctionnalités. De plus, les pages Wiki ont été mises à jour pour la dernière fois en mars 2019. Le projet actuel fournira une nouvelle documentation utilisateur avec une conception moderne et une plus grande facilité d'utilisation pour le port Android.

SITUATION ACTUELLE

Les pages Wiki sont complètement obsolètes et contiennent très peu d'informations sur la dernière version de VLC. De plus, la navigation n'est pas facile. Il n'existe aucune option visible pour lire la documentation dans une autre langue que l'anglais. Il ne contient aucune description de fonctionnalités.

ANALYSE

-> À l'heure actuelle, la documentation actuelle est obsolète et doit être rédigée de manière différente, à l'aide d'une plate-forme et d'outils différents.

-> La plupart des utilisateurs d'Android ont peu ou pas de connaissances techniques. Toutefois, certaines personnes ont besoin d'informations plus techniques sur une fonctionnalité. Il n'est pas judicieux d'écrire et de gérer deux documentations distinctes pour chacun des objectifs ci-dessus. Même dans la même documentation, diviser une fonctionnalité en fonction de son caractère technique ou non technique crée des confusions supplémentaires. Comme la plupart des utilisateurs sont habitués à l'interface utilisateur qu'ils voient ou aux fonctionnalités qu'ils utilisent, il n'est pas facile pour tout le monde de déterminer si un élément est technique ou non. Nous souhaitons donc simplifier cette procédure pour eux.

-> La plupart des utilisateurs essaieront d'obtenir des informations via leur smartphone et le reste via un ordinateur ou d'autres appareils. La documentation doit donc être facilement adaptable à toutes les tailles d'écran. et ne créera aucune confusion quant à la navigation.

-> Toutes les fonctionnalités de la version pour ordinateur ne sont pas disponibles sur Android Port et, le cas échéant, ne fonctionnent pas de la même manière sur les deux ports. En effet, les applications pour ordinateur sont en développement depuis bien plus longtemps et ont atteint un certain niveau de saturation. En revanche, le portage mobile est relativement récent et est encore en développement. En outre, bien que les appareils mobiles soient de plus en plus puissants, il existe des restrictions évidentes sur le type de fonctionnalités que nous pouvons intégrer, principalement en raison de la demande des utilisateurs finaux. Avoir une fonctionnalité que personne n'utilise est un gaspillage de ressources de développement. Il est donc déconseillé de comparer les deux documentations en fonction des fonctionnalités.

EN FONCTION DE L'ANALYSE CI-DESSUS, JE PROPOSE LES INFORMATIONS SUIVANTES. 1. Pour le moment, la documentation destinée aux utilisateurs de l'application de bureau utilise le générateur de documentation Sphinx et le thème Read the Docs. L'utilisation de la même méthode pour le port Android nous aidera de plusieurs manières : -> Fusion facile des deux documentations. -> Elle est optimisée pour toutes les tailles d'écran. -> Expérience fluide lors de la navigation vers la documentation utilisateur Android via la documentation pour ordinateur

1. Séparer les chapitres, les sections et les sous-sections en fonction de leur position relative dans l'application. Par exemple, le mode arrière-plan/PIP se trouve dans Plus > Paramètres > Vidéo. La structure des chapitres sera donc la suivante :

   Plus

   |__Paramètres

   | |__Bibliothèque multimédia

   | |__Vidéo --> Mode arrière-plan/PIP

   : -> Cette approche améliorera la facilité d'accès, car les utilisateurs pourront facilement accéder à la partie où ils ont besoin d'aide en la comparant à l'emplacement relatif dans l'application. Pour chacune des fonctionnalités, nous pouvons séparer les parties techniques et non techniques. Nous devons d'abord rédiger une description simple, puis mettre en évidence ou étiqueter les parties techniques de la même caractéristique, le cas échéant, juste en dessous. Cela peut entraîner quelques répétitions, mais cela garantira une expérience fluide pour une majorité non technique. Cela vous aidera également à améliorer la maintenance à l'avenir. Comme l'application atteindra un état de saturation, l'UI relative ne changera probablement pas beaucoup. Par conséquent, si une nouvelle fonctionnalité est ajoutée ou supprimée, nous pourrons simplement refactoriser la section. Si l'UI entière est modifiée, nous pouvons réorganiser les sections/chapitres ou restructurer l'intégralité du document. Dans les deux cas, nous devons modifier l'intégralité de la documentation, car les captures d'écran doivent être remplacées pour correspondre à l'UI actuelle. Une démonstration fonctionnelle est hébergée ici : https://avinal.gitlab.io/vlc-android-docs/

2. Chaque section de la documentation doit comporter une capture d'écran libellée, une description de la fonctionnalité, une partie plus technique, le cas échéant, et des conseils et astuces pour la fonctionnalité.

-> Le développement indépendant de cette documentation utilisateur sur ordinateur nous aidera à fusionner les deux documentations en quelques étapes seulement, sans affecter la documentation actuelle ni être affecté par elle pendant le développement. Je propose de placer l'ensemble de cette documentation dans la section Android de la documentation pour ordinateur une fois qu'elle sera développée, puis de créer un lien permanent pour la documentation VLC pour Android.

-> D'autres améliorations peuvent inclure la refonte de la page d'accueil de la documentation utilisateur pour ordinateur de bureau afin de permettre aux utilisateurs de choisir directement leur système d'exploitation préféré, puis la redirection vers la documentation correspondante. Étant donné que la documentation utilisateur de VLC pour Windows, macOS et Linux est déjà bien conçue et rédigée, nous pouvons proposer des options entre Windows/MacOS/Linux, Android ou iOS. Vous obtiendrez ainsi une documentation utilisateur bien distincte, mais unifiée, avec un seul lien à utiliser pour tous les ports.

POURQUOI MA DOCUMENTATION UTILISATEUR EST-ELLE MIEUX ? La documentation utilisateur proposée est structurée en fonction des schémas courants suivis par l'utilisateur final pour obtenir de l'aide. La documentation combine toutes les fonctionnalités requises (simplicité, clarté, apparence, connaissances technologiques, etc.) pour maximiser la facilité d'utilisation et l'expérience utilisateur finale. Cette approche est également facile à gérer, car il n'est plus nécessaire de gérer une documentation utilisateur individuelle pour chaque port.

POURQUOI SUIS-JE PERSONNE POUR CE PROJET ? -> J'écris du code depuis deux ans. Je dois souvent consulter la documentation de l'API pour certaines bibliothèques ou certains logiciels, ou même documenter mon propre code. Je sais donc exactement ce que les gens veulent voir dans la documentation, quel problème ils sont confrontés et comment ils abordent pour obtenir de l'aide. Je pourrai appliquer la même expérience pour rédiger une documentation cohérente et facile à lire.

-> J'ai rédigé des articles techniques sur Quora, Stack Overflow et diverses autres plates-formes. Je sais expliquer les choses de manière attrayante et facile à comprendre.

-> VLC pour Android est un outil puissant et très connu, mais la plupart de ses fonctionnalités sont inconnues ou sans aide disponible. J'utilise VLC sur les plates-formes pour ordinateur et mobile depuis de nombreuses années et je sais quels problèmes un utilisateur peut rencontrer. En combinant toutes mes connaissances et mon expérience, je peux vous fournir une documentation de qualité.