Proyecto VideoLAN

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:

VideoLAN

Escritor técnico:

Edidiong Anny Asikpo

Nombre del proyecto:

Moderniza (reescribe) la documentación para usuarios de VLC

Duración del proyecto:

Duración estándar (3 meses)

Project description

RESUMEN

La documentación para los usuarios 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 camino para que los usuarios aprendan a utilizar un software, sus funciones, consejos y trucos, además de resolver problemas comunes que encuentran cuando lo utilizan. 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 porque 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.

En el momento en que se redactó este documento, se accedió a la documentación para usuarios 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 usan 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 del 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 su documentación de usuario para permitir que los usuarios finales tengan una experiencia fluida cuando utilicen el reproductor multimedia VLC.

ESTADO ACTUAL

Actualmente, la documentación del usuario está disponible en una página de wiki. Es obsoleto, está incompleto, es difícil de navegar o 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 causa un gran revés para las personas que no saben leer el inglés.

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

La documentación del usuario propuesta se estructurará para mejorar y garantizar la eficiencia, la coherencia y la tranquilidad del usuario final. Contiene guías escritas y sus imágenes asociadas, incluye instrucciones y explicaciones sobre cómo usar cada función del reproductor multimedia VLC, 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 mejorarla. Él compartió dos vínculos en los que se mostraba un repositorio de Gitlab del archivo fuente escrito con Sphinx y la documentación principal alojada en Read the Docs, y nos dijo que esperaban que la nueva documentación fuera similar a ella. Investigué mucho sobre estas herramientas para comprender mejor cómo funcionan.

Esfinge

Sphinx es una solución sólida y madura de la documentación de software. Incluyen varias funciones que los escritores esperan, como la publicación de fuente única, la reutilización de contenido mediante inclusiones, las inclusiones condicionales basadas en el tipo de contenido y las etiquetas, varios temas HTML antiguos 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 internacionalización. También usa reStructuredText como su lenguaje de marcado, y muchos de sus puntos fuertes provienen de la potencia y la sencillez de reStructuredText y su capacidad para traducir documentación.

Leer los documentos

Leer los Documentos simplifican 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, la función Read the Docs compilará automáticamente tus documentos para que tu código y la documentación estén siempre actualizados. Tiene varias versiones; la lectura de los documentos puede alojar y compilar varias versiones de tus documentos, por lo que tener una versión 1.0 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. Read the Docs es gratuito y de código abierto, y aloja documentación de casi 100,000 proyectos grandes y pequeños en casi todos los lenguajes humanos y informáticos.

VERDICTO

Sphinx es una herramienta increíblemente potente, y la función Read the Docs se basa en la base para proporcionar alojamiento de 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 la documentación de usuario más adecuada para los usuarios finales.

Sphinx incluye compatibilidad para traducir documentación a varios idiomas. Es compatible con el control de versiones, que se usará para administrar la documentación. A diferencia de la wiki actual, en la que cualquier persona puede editar y no agregar la información correcta, este sistema de control de versiones garantizará 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 del 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. Además, es una gran herramienta para usar con la nueva documentación para usuarios de VLC.

No solo leí sobre estas herramientas, también creé un ejemplo básico. 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 puede encontrarse 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 se puede encontrar aquí: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Antes de que comience la implementación de esta nueva estructura, los mentores la deben aprobar. Esto significa que es probable que la estructura cambie después de que los mentores la revisen.

OBJETIVOS DEL PROYECTO

• Reestructura la documentación.
• Actualiza la documentación para adaptarla a las versiones modernas de VLC.
• Se migró la documentación del usuario a GitLab mediante Sphinx y ReadtheDocs.
• Quita las imágenes y la información obsoletas.
• Reescribe la documentación del usuario para que sea más fácil de entender.
• Configúralo para la traducción con la internacionalización de Sphinx.
• Hacer 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 los demás sobre este tema a través de la escritura. En lo personal, siempre me han fascinado los esfuerzos de la comunidad de VideoLAN para crear soluciones de software gratuito para multimedia. En mi infancia, el reproductor multimedia VLC siempre era el software que usaba cuando escuchaba música o miraba una película, 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 adecuada para este proyecto por los siguientes motivos:

• Tengo experiencia previa en la mejora de la documentación de organizaciones y puedo usar cualquier sistema de control de versión, 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 forma más eficiente posible, debes documentarlo. Cuando documentas tus procesos, garantizas eficiencia, coherencia y tranquilidad para todos los involucrados.
• Conozco las necesidades de los usuarios de VLC porque soy uno de ellos. Esto permitirá escribir la documentación de una manera que todos los usuarios del mundo puedan comprenderla a primera vista.