Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- VLC
- Escritor técnico:
- Abhishek Pratap Singh
- Nombre del proyecto:
- Continúa con la modernización de la documentación para usuarios de VLC
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
ESTADO ACTUAL DE LA DOCUMENTACIÓN
La documentación del usuario de VLC está en proceso de modernización y actualización. Se está llevando a cabo la transición para pasar de la documentación anterior basada en wikis[1] a la documentación moderna para usuarios creada en Sphinx[2] alojada en ReadTheDocs.
PÚBLICO OBJETIVO
El público objetivo es tanto un usuario curioso que desea explorar las funciones del reproductor multimedia VLC más allá de un reproductor multimedia común y, hasta cierto punto, ayudará a los desarrolladores también como una guía de referencia sencilla. Por lo tanto, pienso 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 texto de la documentación (especialmente la sección de GUI) debe atenuarse lo suficiente para que una persona con exposición nominal al funcionamiento de computadoras pueda entender e implementar la guía. Por otro lado, no debe ser demasiado largo ni explicativo (especialmente la sección de la CLI) para que los codificadores pierdan interés.
Para lograr el equilibrio adecuado, menciona los requisitos previos al comienzo de la página o incluye secciones opcionales que la persona más capacitado puede omitir.
Para crear las traducciones, el público objetivo son los desarrolladores o usuarios de VLC con un buen dominio del inglés y del idioma al que traducirían las traducciones.
HERRAMIENTAS
Sphinx compila la nueva documentación, que se aloja en ReadTheDocs, y se implementa el sistema de control de versión en GitLab. Tuve experiencia previa en el uso de Git y GitHub, lo que me ayudó a familiarizarme con GitLab, aunque había ciertas funciones diferentes que me llevaban tiempo aprender.
En cuanto a Sphinx, leí al respecto cuando un compañero entusiasta del código abierto comentó cuántas organizaciones lo utilizan para crear su documentación (con el destacado ejemplo de Blender, que usa Sphinx para crear su manual de usuario[3] y documentación de la API[4]).
Tenía un poco de familiaridad con ReadTheDocs, que es una buena herramienta para el control de versiones y para alojar documentación técnica. Por lo tanto, pude compilar documentación de VLC sin muchos problemas y estoy familiarizado con el formato utilizado como texto reestructurado.
En el caso de las traducciones, VLC usa Babel para generar archivos .po a fin de implementar i18n y l10n. En la actualidad, me estoy familiarizando con el flujo de trabajo de Babel y con la forma de compilar archivos .mo con Sphinx.
Quiero usar el período de unión para familiarizarme aún más con las particularidades de las herramientas mencionadas anteriormente.
ENTREGAS Y CRONOGRAMA SEMANAL
Como parte del proyecto de 2019, ya se abordaron algunas 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 la sección de uso avanzado de la documentación del usuario y trabajar en ella.
DELIVERABLE 1 [Week1-2]: Actualiza la documentación de transcodificación, como se menciona en el punto 7[5].
- Transcodificación
- Transcodificar varios videos
- Agregue un logotipo
- Cómo combinar videos
- Extraer audio y extraer audio de un archivo
- Graba un DVD
ENTREGA 2 [Semana 3-4]: Actualiza con VLC como complemento web[6] mientras realizas pruebas en Firefox 77, Chrome 83 y Edge 83.
- Cómo crear páginas web con video
- Incorporar atributos de etiquetas
- Descripción de la API de JavaScript
ENTREGA 3 [Semana 5]: Prueba los comandos de la interfaz de línea de comandos[7] y realiza la actualización según corresponda.
- Reproducciones
- Selección de módulos
- Opciones específicas del elemento
- Filtros
Semana 6: Semana de reserva para las tres entregas anteriores.
ENTREGA 4 [semanas 7-8]: Prepárate para las traducciones. Además de actualizar, me prepararé para las traducciones a otros idiomas. Esto es importante porque, después de la traducción, los usuarios sin experiencia en inglés podrían leer la documentación (y, como nota al margen, VLC estaría un paso más cerca de alcanzar la Dominio[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/voluntario haga lo siguiente:
- Descarga y compila la documentación base de forma local.
- Usa Babel para generar los archivos necesarios.
- Ingresa Translations para las strings.
- Compilación de la documentación traducida con Sphinx.
- Confirma los cambios.
ENTREGA 5 [semanas 9-10]: Prepárate para la documentación de los módulos. Como acordamos con los mentores, me preparo para preparar la documentación de los módulos en dos partes.
Parte I: Crear archivos cerca de los módulos a través de un script que busca opciones válidas de la base de código y extrae su uso en una línea (y valores predeterminados) de las páginas wiki correspondientes. Esto servirá como borrador básico.
Parte 2: Crear una estructura específica de la plataforma que vincule todos los módulos + complementos + opciones para una plataforma determinada (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 abajo arriba, la documentación principal de los módulos se crearía combinando 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án una revisión, pero la primera prioridad es crear un framework funcional. Una vez que se logra ese objetivo, y según el tiempo disponible, revisaría los archivos para verificar las opciones. Se está priorizando el framework, ya que una vez que esté disponible, los desarrolladores y encargados de mantenimiento también podrán comenzar a contribuir agregando casos de uso relevantes.
ENTREGA ADICIONAL [Semana 11]: Prepárate para la versión 4.0. En caso de que el proyecto se mantenga dentro del plazo previsto, me gustaría proponer un entregable adicional. Como se explicó con los mentores, prepararse para la versión 4.0 implica tener una documentación estable y casi completa para la versión 3.0.
Por lo tanto, revisaría la documentación ya completa de las siguientes secciones para verificar y actualizar los métodos mencionados:
- Uso básico: Contenido multimedia, reproducción, audio, video, subtítulos, teclas de acceso rápido, grabaciones, configuración, sugerencias y trucos.
- Uso avanzado: Reproductores, Interfaz, transcodificación, Transmisión y Casos Inusuales.
- Complementos: extensiones, skins.
Semana 12: Semana de reserva para los tres entregables anteriores + los 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 intentar darle sentido a 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 modificaciones con VLC :)
Además, fui investigadora y escritora toda mi vida. A menos que escriba algo, nunca lo entiendo realmente, y este hábito me convirtió en una persona eficiente para tomar notas y documentar.
La intersección de estos dos hábitos es lo que me convierte en una opción adecuada para la documentación técnica. Puedo avanzar a través de los aspectos técnicos y documentar mis hallazgos/procesos de una manera que los usuarios puedan comprender.
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/lc [4] https://docs.blender.org/api/current/videoindex.lan/