Proyecto VideoLAN

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

Resumen del proyecto

Organización de código abierto:
VideoLAN
Redactor técnico:
Edidiong Anny Asikpo
Nombre del proyecto:
Moderniza (rescribe) la documentación para usuarios de VLC
Duración del proyecto:
Duración estándar (3 meses)

Project description

RESUMEN

La documentación del usuario está diseñada para ayudar a los usuarios finales a utilizar un producto o servicio. Una buena documentación para el usuario es muy importante porque proporciona un medio para que los usuarios aprendan a usar un software, sus funciones, consejos y trucos, y también resuelven problemas comunes que encuentran cuando utilizan el software. También reduce el costo de asistencia y forma parte de la identidad corporativa del producto: una buena documentación para el usuario es una señal de buen estado del producto, el equipo de desarrolladores.

Sin una buena documentación del usuario, es posible que un usuario no sepa cómo hacer las cosas anteriores de manera efectiva y eficiente. La documentación del usuario puede desempeñar un papel fundamental para garantizar el éxito de un producto, ya que una buena comunicación es y será siempre el centro de cualquier negocio o producto, y una gran documentación solo toma esa comunicación y la coloca en un marco manejable al que todos pueden acceder para tener éxito.

Al momento de la redacción de este documento, se ha accedido a la documentación del usuario de VLC 4 634 065 veces y el reproductor multimedia VLC se descarga aproximadamente 23 millones de veces al mes desde el sitio web principal. Esto demuestra que muchas personas en todo el mundo utilizan el reproductor multimedia VLC y pueden querer leer la documentación del usuario para obtener orientación sobre cómo utilizar el reproductor multimedia. Sin embargo, la documentación para el usuario del reproductor multimedia VLC está desactualizada e incompleta (se modificó por última vez el 28 de octubre de 2015), y la comunidad de VideoLAN quiere usar este proyecto para mejorar la documentación del usuario y permitir que los usuarios finales tengan una experiencia fluida cuando utilizan el reproductor multimedia VLC.

ESTADO ACTUAL

Actualmente, la documentación del usuario está disponible en una página de wiki. Es obsoleta, incompleta, difícil de navegar o de encontrar información, no cubre la información sobre la versión actual del reproductor multimedia y solo se puede traducir al alemán, lo que genera un gran obstáculo para las personas que no saben leer el idioma inglés.

¿POR QUÉ MI DOCUMENTACIÓN PROPUESTA DE USUARIO ES UNA MEJORA SOBRE LA ACTUAL?

La documentación propuesta para el usuario se estructurará para mejorar y garantizar la eficiencia, la coherencia y la tranquilidad para el usuario final. Contiene guías escritas y sus imágenes asociadas, así como instrucciones y explicaciones sobre cómo usar cada función de VLC Media Player, actualizadas, fáciles de navegar, comprensibles y traducibles en al menos cinco idiomas principales.

Mentores: Jean-Baptiste, Alex, Simon

ANÁLISIS

Jean-Baptiste y yo tuvimos una conversación sobre el nuevo entorno al que se migraría la documentación del usuario actual para realizar mejoras. Él compartió dos vínculos que mostraban un repositorio de Gitlab del archivo fuente escrito con Sphinx y la documentación principal alojada en Leer los documentos, y nos dijo que esperaban que la nueva documentación fuera similar a este. Investigué mucho sobre estas herramientas para comprender mejor cómo funcionan.

Esfinge

Sphinx es una solución sólida y consolidada para la documentación de software. Incluye una serie de funciones que los escritores esperan, como la publicación de una sola fuente, la reutilización de contenido a través de inclusiones, las inclusiones condicionales según el tipo de contenido y las etiquetas, varios temas de HTML consolidados que proporcionan una excelente experiencia del usuario en dispositivos móviles y computadoras de escritorio, hacen referencia a todas las páginas, documentos y proyectos, compatibilidad con índices y glosarios, y compatibilidad con la internacionalización. También usa reStructuredText como su lenguaje de marcado, y muchas de sus fortalezas provienen del poder y la practicidad de reStructuredText y su capacidad para traducir documentación.

Leer los documentos

Lee Documentos simplifica la documentación del software, ya que automatiza la compilación, el control de versiones y el alojamiento de tus documentos. Nunca se desincroniza; es decir, cada vez que envías código a tu sistema de control de versión favorito, ya sea Git, Mercurial, Bazaar o Subversion, Read the Docs compilará automáticamente tus documentos para que el código y la documentación estén siempre actualizados. Tiene varias versiones; la lectura del documento puede alojar y compilar varias versiones de tus documentos, por lo que tener una versión 1.0 de tus documentos y una versión 2.0 de tus documentos es tan fácil como tener una rama o etiqueta separada en tu sistema de control de versión. Lee Documentos es un documento gratuito y de código abierto que aloja documentación de casi 100,000 proyectos grandes y pequeños de este tipo en casi todos los lenguajes humanos y informáticos.

VEREDICTO

Sphinx es una herramienta increíblemente potente. La función de leer los documentos se basa en las compilaciones de la parte superior para proporcionar alojamiento para la documentación de Sphinx que mantiene los documentos actualizados en todas las versiones. En conjunto, constituyen un conjunto maravilloso de herramientas que los desarrolladores y los escritores técnicos pueden usar para crear documentación de usuario que se adapte mejor a los usuarios finales.

Sphinx incluye compatibilidad para traducir documentación a varios idiomas. Admite el control de versiones, que se usará para administrar la documentación. A diferencia de la wiki actual, donde cualquiera puede editar y no agregar la información correcta, este sistema de control de versiones asegurará que todos los cambios se revisen primero antes de fusionarse con el repositorio principal. El control de versión también hará que la documentación aumente la contribución de código abierto al proyecto, ya que las personas pueden crear problemas, abrir solicitudes de extracción, etc. Sphinx y la lectura de los Documentos se usan en una lista de otras grandes comunidades como ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, etc. Es una gran herramienta para usar en la nueva documentación para usuarios de VLC.

No leí sobre estas herramientas, también creé una muestra básica. Este es el vínculo: https://gitlab.com/Didicodes/demo-vlc-user-documentation a mi repositorio de Gitlab, mientras que la versión alojada en readthedocs se puede encontrar aquí: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/).

ESTRUCTURA DE LA DOCUMENTACIÓN PROPUESTA

Creé una estructura para la documentación del usuario de VLC, que puedes encontrar aquí: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Antes de que comience la implementación de esta nueva estructura, deben contar con la aprobación de los mentores. Esto significa que es probable que la estructura cambie después de que los mentores la hayan revisado.

OBJETIVOS DEL PROYECTO

  • Reestructura la documentación.
  • Actualiza la documentación para adaptarla a las versiones modernas de VLC.
  • Migrar la documentación del usuario a GitLab mediante Sphinx y ReadtheDocs
  • Quita las imágenes y la información obsoletas.
  • Vuelve a escribir la documentación del usuario para que sea más fácil de comprender.
  • Configúralo para la traducción con Sphinx Internationalization.
  • Haz que la documentación sea impulsada por la comunidad para que los usuarios puedan informar o resolver cualquier problema que encuentren mientras leen la documentación.

¿POR QUÉ ESTE PROYECTO?

Siempre he tenido la convicción de que escribir código, resolver problemas y compilar software alcanza todo su potencial cuando también se puede informar a otros sobre este tema a través de la escritura. En lo personal, siempre me han fascinado los esfuerzos de la comunidad VideoLAN para crear soluciones de software gratuito para archivos multimedia. En mi infancia, el reproductor multimedia VLC siempre era el software que usaba para escuchar música o mirar películas, ya que era muy ruidoso y tenía muchas funciones. Será un honor trabajar con la comunidad que contribuyó a que mi infancia fuera increíble.

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

Creo que soy la persona indicada para este proyecto por los siguientes motivos:

  • Tengo experiencia previa en la mejora de la documentación de las organizaciones y puedo usar cualquier sistema de control de versiones, por lo que ejecutar comandos en Gitab no será un problema. Además, lo que me impulsa es trabajar en proyectos que crean valor para las personas.
  • Creo que si quieres que alguien haga algo de la manera más eficiente posible, debes documentarlo. Al documentar tus procesos, garantizas eficiencia, coherencia y tranquilidad a todos los involucrados.
  • Conozco las necesidades de los usuarios de VLC porque yo soy uno de ellos. Esto permitirá escribir la documentación de forma que todos los usuarios del mundo puedan comprenderla a primera vista.