Proyecto de VLC

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.

Resumen del proyecto

Organización de código abierto:

VLC

Redactor técnico:

Abhishek Pratap Singh

Nombre del proyecto:

Continuar con la modernización de la documentación para el usuario de VLC

Duración del proyecto:

Duración estándar (3 meses)

Project description

ESTADO ACTUAL DE LA DOCUMENTACIÓN

La documentación para el usuario de VLC está en proceso de modernización y actualización. Se está realizando la transición de la documentación anterior basada en wiki[1] a la documentación moderna para el usuario compilada con Sphinx[2] alojada en ReadTheDocs.

PÚBLICO OBJETIVO

El público objetivo es un usuario curioso que desea explorar las funciones del reproductor multimedia VLC más allá de un reproductor multimedia ordinario y, en cierta medida, también ayudará a los desarrolladores, ya que servirá como una guía de referencia fácil. Por lo tanto, planeo incluir instrucciones basadas en GUI (junto con imágenes cuando corresponda) y métodos basados en CLI (junto con fragmentos de código) para que el usuario final tenga libertad de elección.

Creo que el lenguaje de la documentación (en especial, la sección de la GUI) debería ser lo suficientemente sencillo para que una persona con una exposición nominal a la operación de computadoras pueda comprender e implementar la guía. Por otro lado, no debe ser demasiado largo o explicativo (en especial, la sección de la CLI) para que los programadores pierdan interés.

Para lograr el equilibrio adecuado, menciona los requisitos previos al comienzo de la página o mantén secciones opcionales que los usuarios con más conocimientos puedan omitir.

Para crear traducciones, el público objetivo son los desarrolladores o usuarios de VLC que comprenden bien el inglés y el idioma al que traducirían.

HERRAMIENTAS

Sphinx compila la nueva documentación y la aloja en ReadTheDocs, y el sistema de control de versiones se implementa en GitLab. Ya había usado Git y GitHub, lo que me ayudó a familiarizarme con GitLab, aunque algunas funciones diferentes me llevaron un tiempo aprender a usar.

En cuanto a Sphinx, había leído sobre él cuando un entusiasta del código abierto comentó cuántas organizaciones lo usan para compilar su documentación (con el ejemplo notable de Blender, que usa Sphinx para compilar su manual de usuario[3] y su documentación de la API[4]).

Estaba un poco familiarizado con ReadTheDocs, que es una buena herramienta para el control de versiones y para alojar documentación técnica. Por lo tanto, pude compilar la documentación de VLC sin muchos problemas y estoy familiarizado con reStructured Text, el formato que se usa.

En el caso de las traducciones, VLC usa Babel para generar archivos .po a fin de implementar i18n y l10n. Actualmente, me estoy familiarizando con el flujo de trabajo de Babel y cómo compilar archivos .mo con Sphinx.

Tengo la intención de utilizar el período de vinculación para familiarizarme más con las particularidades de las herramientas mencionadas anteriormente.

ENTREGABLES Y CRONOGRAMA SEMANAL

Como parte del proyecto de 2019, ya se abordaron partes de la instalación, la interfaz, el audio, el video, la reproducción, etc. (la mayoría de las funciones básicas). Por lo tanto, para el proyecto de 2020, me gustaría actualizar y trabajar en la sección de uso avanzado de la documentación del usuario.

ENTREGA 1 [Semana 1-2]: Actualiza la documentación de transcodificación, como se menciona en la pregunta n.o 7[5].

• transcodificar
• Transcodifica varios videos
• Agregue un logotipo
• Cómo combinar videos
• Extraer audio y Extraer audio de un archivo
• Extraer un DVD

PRODUCTO 2 [Semana 3-4]: Actualiza el uso de VLC como complemento web[6] mientras realizas pruebas en Firefox 77, Chrome 83 y Edge 83.

• Cómo crear páginas web con video
• Cómo incorporar atributos de etiqueta
• Descripción de la API de JavaScript

ENTREGA 3 [Semana 5]: Prueba los comandos de la interfaz de línea de comandos[7] y actualízala según corresponda.

• Transmisiones
• Selección de módulos
• Opciones específicas del artículo
• Filtros

Semana 6: Semana de reserva para las tres entregas anteriores.

ENTREGA 4 [semanas 7 y 8]: Prepárate para las traducciones. Además de actualizar, me prepararé para las traducciones a otros idiomas. Esto es importante, ya que, después de la traducción, los usuarios sin experiencia en inglés podrán leer la documentación (y, como nota al margen, VLC estaría un paso más cerca de alcanzar la dominación del mundo[8]).

Como se mencionó en la sección Herramientas de la propuesta, actualmente VLC usa Babel para generar archivos .po para las traducciones. Documentaré el proceso para que un usuario o voluntario haga lo siguiente:

• Descarga y compila la documentación base de forma local.
• Usa Babel para generar los archivos necesarios.
• Ingresa las traducciones para las cadenas.
• Compilación de la documentación traducida con Sphinx.
• Confirma los cambios.

PRODUCTO 5 [Semanas 9 y 10]: Prepárate para la documentación de los módulos. Como comentamos con los mentores, pienso prepararme para la documentación de los módulos en dos partes.

Parte I: Crea archivos cerca de los módulos a través de una secuencia de comandos que busca opciones válidas en la base de código y extrae su uso de una línea (y los valores predeterminados) de las páginas de la wiki correspondientes. Esto serviría como borrador básico.

Parte II: Compila una estructura específica de la plataforma que vincule todos los módulos, complementos y opciones para una plataforma en particular (Windows y, si el tiempo lo permite, también para Fedora).

Crear archivos cerca de los módulos garantizará que la documentación esté cerca del código fuente. Con un enfoque de la parte inferior a la superior, la documentación principal de los módulos se compilaría a partir de la combinación de los archivos de la Parte I y usando la estructura de la Parte II como referencia.

Los archivos creados a través de la automatización necesitarían una revisión, pero la primera prioridad es crear un framework funcional. Una vez que se logre, y según el tiempo disponible, revisaré los archivos para verificar las opciones. Se le está dando prioridad al framework porque, una vez que esté disponible, los desarrolladores y los encargados del mantenimiento también podrán comenzar a contribuir agregando casos de uso relevantes.

ENTREGA DE BONUS [Semana 11]: Prepárate para el lanzamiento de la versión 4.0. En caso de que el proyecto se mantenga dentro del cronograma, me gustaría proponer un entregable adicional. Como se discutió con los mentores, prepararse para el lanzamiento de la versión 4.0 implica tener una documentación estable y casi completa de la versión 3.0.

Por lo tanto, revisaría la documentación ya completada de las siguientes secciones para verificar y actualizar los métodos mencionados:

• Uso básico: contenido multimedia, reproducción, audio, video, subtítulos, combinaciones de teclas, grabaciones, configuración, sugerencias y trucos.
• Uso avanzado: reproductor, interfaz, transcodificación, transmisión, casos inusuales.
• Complementos: Extensiones y temas.

Semana 12: Semana de reserva para las tres entregas anteriores + informes finales.

¿POR QUÉ SOY LA PERSONA ADECUADA PARA ESTE PROYECTO?

Como entusiasta de la tecnología, tengo experiencia en el uso y la prueba de software y, a veces, en tratar de entender sus bases de código. De hecho, tratar de comprender la base de código de una organización de código abierto fue la primera vez que realmente me di cuenta de la importancia de la documentación. Además, como entusiasta de la música, tengo mucha experiencia en hacer ajustes con VLC :)

Aparte de eso, he sido investigadora y escritora toda mi vida. A menos que escriba algo, nunca lo entiendo realmente, y este hábito me ha convertido en una persona eficiente para tomar notas y documentar.

La intersección de estos dos hábitos es lo que me hace adecuado para la documentación técnica. Puedo encontrar mi camino a través de los aspectos técnicos y documentar mis hallazgos o procesos de una manera que los usuarios entiendan.

Vínculos: [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