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:
- VLC
- Rédacteur technique:
- Abhishek Pratap Singh
- Nom du projet:
- Poursuivre la modernisation de la documentation utilisateur de VLC
- Durée du projet:
- Durée standard (3 mois)
Project description
ÉTAT ACTUEL DE LA DOCUMENTATION
La documentation utilisateur VLC est en cours de modernisation et de mise à jour. La transition est en cours pour passer de l'ancienne documentation basée sur wiki[1] à la documentation utilisateur moderne conçue par le sphinx[2], hébergée sur ReadTheDocs.
TARGET AUDIENCE
L'audience cible est à la fois un utilisateur curieux qui souhaite explorer les fonctionnalités du lecteur multimédia VLC au-delà d'un lecteur multimédia ordinaire. Dans une certaine mesure, il servira également de guide de référence pour les développeurs. Par conséquent, je prévois d'inclure à la fois des instructions basées sur l'IUG (ainsi que 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 IUG) doit être suffisamment réduit pour qu'une personne ayant une exposition nominale aux ordinateurs en exploitation soit en mesure de comprendre et de mettre en œuvre le guide. D'un autre côté, il ne doit pas être trop long ni explicatif (en particulier la section CLI) que les codeurs perdent de l'intérêt.
Pour trouver le bon équilibre, il suffit de mentionner les prérequis au début de la page ou de conserver des sections facultatives que les experts peuvent ignorer.
L'audience cible est constituée de développeurs/utilisateurs de VLC qui maîtrisent l'anglais et la langue cible.
OUTILS
La nouvelle documentation est conçue par Sphinx et hébergée sur ReadTheDocs, et le système de contrôle des versions est implémenté dans GitLab. J'ai déjà utilisé Git et GitHub, ce qui m'a aidé à appréhender GitLab, bien que certaines fonctionnalités différentes aient nécessité un certain temps d'apprentissage.
En ce qui concerne Sphinx, j'en avais lu lorsqu'un collègue passionné de l'Open Source avait remarqué le nombre d'organisations qui l'utilisaient pour créer leur documentation (avec l'exemple remarquable de Blender, qui utilise Sphinx pour la création de leur manuel utilisateur[3] et de la documentation de l'API[4]).
Je connaissais un peu ReadTheDocs, qui est un bon outil pour la gestion des versions et l'hébergement de documentation technique. Par conséquent, j'ai pu créer de la documentation VLC sans rencontrer de problème, et je suis familiarisé avec le texte restructuré, la mise en forme utilisée.
Pour les traductions, VLC utilise Babel pour générer des fichiers .po afin d'implémenter i18n et l10n. Je connais actuellement 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.
LIVRAISONS ET CALENDRIER HEBDOMADAIRE
Dans le cadre du projet 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à abordées. Par conséquent, pour le projet 2020, j'aimerais mettre à jour et travailler sur la section sur l'utilisation avancée de la documentation utilisateur.
DIFFUSION 1 [Semaine1-2]: mettre à jour la documentation de transcodage, comme indiqué au point 7[5].
- Transcodage
- Transcodage de plusieurs vidéos
- Ajoutez un logo
- Fusionner des vidéos
- Extraire le contenu audio d'un fichier et extraire l'audio d'un fichier
- Extraire un DVD
DIFFUSABLE 2 [semaines 3-4]: mise à jour à l'aide de VLC comme plug-in Web[6] lors des tests dans Firefox 77, Chrome 83 et Edge 83.
- Créer des pages Web contenant des vidéos
- Attributs de tag Embed
- Description de l'API JavaScript
DIFFUSION 3 [Semaine 5]: testez les commandes de l'interface de ligne de commande[7] et effectuez les mises à jour nécessaires.
- Diffusions
- Sélection des modules
- Options spécifiques aux articles
- Filtres
Semaine 6: semaine tampon pour les trois produits livrables ci-dessus.
LIVRAISON 4 [Semaine 7-8]: Préparez-vous pour les traductions. En plus de la mise à jour, je vais préparer les traductions dans d'autres langues. C'est important, car après la traduction, les utilisateurs sans expérience anglaise pourront lire la documentation (et, en revanche, VLC serait un pas de plus vers la domination du monde[8]).
Comme indiqué dans la section "Tools" (Outils) de la proposition, VLC utilise actuellement Babel pour générer des fichiers .po à des fins de traduction. Je vais documenter la procédure pour un utilisateur/bénévole afin de:
- Téléchargez et créez la documentation de base en local.
- Utilisez Babel pour générer les fichiers requis.
- Saisissez les traductions pour les chaînes.
- Créer la documentation traduite à l'aide de Sphinx
- Validez les modifications.
DIFFUSION 5 [Semaine 9-10]: préparez-vous pour la documentation sur les modules. Comme nous en avons parlé avec les mentors, je prévois de préparer la documentation des modules en deux parties.
Partie 1 - Créer des fichiers à proximité des modules à l'aide d'un script qui recherche les options valides dans le codebase et extrait leur utilisation sur une ligne (et les valeurs par défaut) des pages wiki correspondantes. Cela servirait de brouillon de base.
Partie II: Créer une structure spécifique à la plate-forme qui associe tous les modules, plug-ins et options pour une plate-forme spécifique (Windows et, si le temps le permet, également pour Fedora).
La création de fichiers à proximité des modules garantit que la documentation est proche du code source. En utilisant une approche de bas en haut, la principale documentation des modules serait constituée en combinant les fichiers créés dans la Partie I et en utilisant la structure faite dans la Partie II comme référence.
Les fichiers créés par l'automatisation nécessitent un examen, mais la première priorité est de créer un framework fonctionnel. Une fois que cela aura été fait, et selon les créneaux disponibles, j'examinerai les fichiers pour vérifier les options. Nous donnons la priorité au framework, car une fois qu'il est disponible, les développeurs et les responsables peuvent également commencer à apporter leur contribution en ajoutant des cas d'utilisation pertinents.
DIFFUSION BONUS [Semaine 11]: préparez-vous pour la version 4.0. Si le projet respecte le calendrier, j'aimerais proposer un produit livrable bonus. Comme nous l'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.
Par conséquent, je consulte la documentation déjà complétée des sections suivantes pour vérifier et mettre à jour les méthodes mentionnées:
- Utilisation de base: contenus multimédias, lecture, audio, vidéo, sous-titres, raccourcis clavier, 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 produits livrables ci-dessus + rapports finaux.
POURQUOI SUIS-JE LA PERSONNE À SUIVRE POUR CE PROJET ?
En tant que passionné de technologie, j'ai de l'expérience dans l'utilisation et le test de logiciels et, parfois, j'essaie de comprendre leur codebase. En fait, c'était d'essayer de comprendre le code base d'une organisation Open Source pour la première fois que je réalisais vraiment l'importance de la documentation. De plus, en tant qu'amateur de musique, j'ai beaucoup d'expérience en matière d'optimisation avec VLC :)
En dehors de cela, j'ai été chercheuse et écrivaine toute ma vie. À moins d'écrire quelque chose, je ne le comprends jamais vraiment et cette habitude a fait de moi une prise de notes et un documenteur efficace.
Le croisement de ces deux habitudes est ce qui fait de moi une bonne personne pour la documentation technique. Je peux parcourir les aspects techniques et documenter mes découvertes/processus de manière à ce que les utilisateurs comprennent les informations dont ils ont besoin.
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://vlc-user-documentation.videolan.