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:
- Abhishek Pratap Singh
- Nom du projet:
- Poursuite de la modernisation de la documentation utilisateur de VLC
- Durée du projet:
- Durée standard (trois mois)
Project description
ÉTAT ACTUEL DE LA DOCUMENTATION
La documentation utilisateur de VLC est en cours de modernisation et de mise à jour. La transition de l'ancienne documentation basée sur le wiki[1] vers la documentation utilisateur moderne basée sur Sphinx[2] hébergée sur ReadTheDocs est en cours.
AUDIENCE CIBLE
L'audience cible est à la fois un utilisateur curieux qui souhaite explorer les fonctionnalités de VLC Media Player au-delà d'un lecteur multimédia ordinaire et, dans une certaine mesure, les développeurs, qui pourront s'appuyer sur ce guide de référence facile à consulter. Par conséquent, je prévois d'inclure à la fois des instructions basées sur l'IUG (avec des images, le cas échéant) et des méthodes basées sur la CLI (avec des extraits de code) afin que l'utilisateur final ait le choix.
Je pense que le langage de la documentation (en particulier la section sur l'IUG) doit être suffisamment atténué pour qu'une personne ayant une exposition nominale à l'utilisation d'ordinateurs puisse comprendre et mettre en œuvre le guide. D'un autre côté, il ne doit pas être trop long ni trop explicatif (en particulier la section sur la CLI) pour que les codeurs ne perdent pas leur intérêt.
Pour trouver le juste équilibre, vous pouvez mentionner les prérequis au début de la page ou conserver des sections facultatives que les personnes expérimentées peuvent ignorer.
Pour créer des traductions, l'audience cible est constituée des développeurs/utilisateurs de VLC qui maîtrisent bien l'anglais et la langue dans laquelle ils souhaitent traduire.
OUTILS
La nouvelle documentation est créée par Sphinx et hébergée sur ReadTheDocs. Le système de contrôle des versions est implémenté dans GitLab. J'avais déjà utilisé Git et GitHub, ce qui m'a aidé à comprendre GitLab, même si certaines fonctionnalités différentes ont pris un certain temps à apprendre.
J'ai découvert Sphinx lorsqu'un autre passionné du logiciel Open Source a fait remarquer que de nombreuses organisations l'utilisent pour créer leur documentation (avec l'exemple notable de Blender, qui utilise Sphinx pour créer son manuel utilisateur[3] et sa documentation d'API[4]).
Je connaissais un peu ReadTheDocs, qui est un bon outil pour gérer les versions et héberger la documentation technique. J'ai donc pu créer la documentation VLC sans trop de problèmes et je suis familiarisé avec le formatage utilisé, à savoir reStructured Text.
Pour les traductions, VLC utilise Babel afin de générer des fichiers .po pour i18n et l10n. Je me familiarise actuellement avec le workflow Babel et la création de fichiers .mo à l'aide de Sphinx.
J'ai l'intention d'utiliser la période d'association pour me familiariser davantage avec les subtilités des outils mentionnés ci-dessus.
LIVRABLES ET CALENDRIER HEBDOMADAIRE
Dans le cadre du projet de 2019, certaines parties de l'installation, de l'interface, de l'audio, de la vidéo, de la lecture, etc. (la plupart des fonctionnalités de base) sont déjà couvertes. Par conséquent, pour le projet 2020, je souhaite mettre à jour et travailler sur la section d'utilisation avancée de la documentation utilisateur.
DIFFUSION 1 [Semaine 1-2]: mettez à jour la documentation sur le transcodage, comme indiqué à l'étape 7[5].
- Transcodage
- Transcoder plusieurs vidéos
- Ajoutez un logo
- Fusionner des vidéos
- Extraire l'audio et Extraire l'audio d'un fichier
- Extraire un DVD
PRODUIT 2 [Semaines 3 à 4]: Mise à jour de l'utilisation de VLC en tant que plug-in Web[6], lors des tests dans Firefox 77, Chrome 83 et Edge 83.
- Créer des pages Web avec des vidéos
- Intégrer des attributs de balise
- Description de l'API JavaScript
PRODUIT 3 [Semaine 5]: Testez les commandes de l'interface de ligne de commande[7] et mettez-les à jour en conséquence.
- Flux
- Sélection des modules
- Options spécifiques à l'article
- Filtres
Semaine 6: semaine de marge pour les trois livrables ci-dessus.
PRODUIT 4 [Semaines 7 à 8]: Préparation des traductions En plus de la mise à jour, je vais préparer les traductions dans d'autres langues. Cela est important, car après la traduction, les utilisateurs qui ne parlent pas anglais pourront lire la documentation (et, en passant, VLC sera un peu plus près de dominer le monde[8]).
Comme indiqué dans la section "Outils" de la proposition, VLC utilise actuellement Babel pour générer des fichiers .po destinés aux traductions. Je vais documenter le processus permettant à un utilisateur/bénévole de:
- Téléchargez et créez la documentation de base localement.
- Utilisez Babel pour générer les fichiers requis.
- Saisissez les traductions pour les chaînes.
- Création de la documentation traduite à l'aide de Sphinx.
- Effectuez un commit sur les modifications :
PRODUIT 5 [Semaines 9-10]: Préparation de la documentation des modules. Comme discuté avec les mentors, je prévois de me préparer à la documentation des modules en deux parties.
Partie - I: création de fichiers à proximité des modules à l'aide d'un script qui recherche les options valides dans le code base et extrait leur utilisation sur une ligne (et leurs valeurs par défaut) des pages wiki correspondantes. Il s'agit d'un brouillon de base.
Partie 2: Créer une structure spécifique à une plate-forme qui relie tous les modules, plug-ins et options d'une plate-forme particulière (Windows et, si le temps le permet, pour Fedora).
En créant des fichiers à proximité des modules, vous vous assurez que la documentation est proche du code source. En appliquant une approche ascendante, la documentation principale des modules sera créée en combinant les fichiers créés dans la partie I et en utilisant la structure créée dans la partie II comme référence.
Les fichiers créés par automatisation doivent être examinés, mais la première priorité est de créer un framework fonctionnel. Une fois cela fait, et en fonction du temps disponible, je vais examiner les fichiers pour vérifier les options. Le framework est prioritaire, car une fois qu'il sera disponible, les développeurs et les responsables de la maintenance pourront également commencer à contribuer en ajoutant des cas d'utilisation pertinents.
DOCUMENT LIVRABLE BONUS [Semaine 11]: Préparation de la version 4.0 Si le projet reste dans les délais, je souhaite proposer un produit livrable bonus. Comme nous en avons discuté avec les mentors, la préparation de la version 4.0 implique de disposer d'une documentation stable et presque complète pour la version 3.0.
Je vais donc examiner la documentation déjà terminée des sections suivantes pour vérifier et mettre à jour les méthodes mentionnées:
- Utilisation de base: multimédia, lecture, audio, vidéo, sous-titres, touches de raccourci, enregistrements, paramètres, conseils et astuces.
- Utilisation avancée: lecteur, interface, transcodage, streaming, cas inhabituels.
- Modules complémentaires: extensions, skins.
Semaine 12: semaine tampon pour les trois livrables ci-dessus et les rapports finaux.
POURQUOI SUIS-JE LA PERSONNE ADÉQUATE POUR CE PROJET ?
En tant qu'amateur de technologie, j'ai de l'expérience dans l'utilisation/le test de logiciels et parfois, j'essaie de comprendre leur base de code. En fait, essayer de comprendre le code base d'une organisation Open Source était la première fois que j'ai vraiment réalisé l'importance de la documentation. De plus, en tant que passionné de musique, j'ai beaucoup d'expérience dans la configuration de VLC.
En dehors de cela, j'ai été chercheur et écrivain toute ma vie. À moins d'écrire quelque chose, je ne le comprends jamais vraiment, et cette habitude a fait de moi une personne qui prend des notes et qui documente efficacement.
C'est l'intersection de ces deux habitudes qui me permet de m'épanouir dans la documentation technique. Je sais m'orienter dans les aspects techniques et documenter mes résultats/processus de manière à ce que les utilisateurs les comprennent.
Liens : [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35