Se usó la API de Cloud Translation para traducir esta página.

Proyecto VideoLAN

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:: VideoLAN
Escritor técnico:: Edidiong Anny Asikpo
Nombre del proyecto:: Moderniza (reescribe) la documentación del usuario de VLC
Duración del proyecto:: Duración estándar (3 meses)

Project description

ABSTRACT

La documentación para usuarios está diseñada para ayudar a los usuarios finales a usar un producto o servicio. Una buena documentación para el usuario es muy importante porque les brinda a los usuarios una forma de aprender a usar un software, sus funciones, sugerencias y trucos, y también resolver problemas comunes que se encuentran cuando se usa 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 un signo de que el producto y el equipo de desarrolladores están en buen estado.

Sin una buena documentación de usuario, es posible que un usuario no sepa cómo hacer todo lo anterior de manera efectiva y eficiente. La documentación del usuario puede desempeñar un papel fundamental a la hora de garantizar el éxito de un producto porque una buena comunicación siempre será y será el núcleo de cualquier negocio o producto. Una gran documentación simplemente 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 había accedido a la documentación de usuario de VLC 4,634,065 veces, y el reproductor multimedia de VLC se descargaba 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 es posible que quieran leer su documentación de usuario para obtener orientación sobre cómo usar el reproductor multimedia. Sin embargo, la documentación para el usuario del reproductor multimedia VLC está desactualizada y es incompleta (se modificó por última vez el 28 de octubre de 2015). La comunidad de VideoLAN quiere usar este proyecto para mejorar la documentación para el usuario y permitir que los usuarios finales tengan una experiencia fluida cuando usen el reproductor multimedia VLC.

ESTADO ACTUAL

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

¿POR QUÉ MI DOCUMENTACIÓN DEL USUARIO PROPUESTA ES UNA MEJORA CON RESPECTO A LA ACTUAL?

La documentación para el usuario propuesta se estructurará para mejorar y garantizar la eficiencia, la coherencia y la tranquilidad para el usuario final. Incluirá guías escritas y sus imágenes asociadas, así como instrucciones y explicaciones sobre cómo usar cada función del reproductor multimedia VLC, actualizado, fácil de navegar, comprensible y traducible en al menos cinco idiomas principales.

Mentores: Jean-Baptiste, Alex y Simon

ANÁLISIS

Jean-Baptiste y yo tuvimos una conversación sobre el nuevo entorno al que se migraría la documentación de usuario actual para realizar mejoras, y é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 dijo que esperaban que la nueva documentación sea 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 documentación de software. Incluye varias funciones que esperan los escritores, como la publicación de una sola fuente, la reutilización de contenido a través de incorporaciones, incorporaciones condicionales basadas en el tipo de contenido y las etiquetas, varios temas HTML maduros que proporcionan una excelente experiencia del usuario en dispositivos móviles y computadoras de escritorio, referencias en páginas, documentos y proyectos, compatibilidad con índices y glosarios, y compatibilidad con la internacionalización. También usa reStructuredText como lenguaje de marcado, y muchas de sus fortalezas provienen de la potencia y la sencillez de reStructuredText y su capacidad para traducir documentación.

Leer los documentos

Read the Docs simplifica la documentación de software automatizando la compilación, el control de versiones y el alojamiento de tus documentos. Nunca se desincroniza, es decir, cada vez que envíes código a tu sistema de control de versiones 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. Read the Docs puede alojar y compilar varias versiones de tus documentos, por lo que tener una versión 1.0 y una 2.0 es tan fácil como tener una rama o etiqueta independiente en tu sistema de control de versiones. Read the Docs es gratuito y de código abierto, y aloja documentación de casi 100,000 proyectos de código abierto grandes y pequeños en casi todos los lenguajes humanos y de programación.

VERDICT

Sphinx es una herramienta increíblemente potente, y Read the Docs se basa en ella para proporcionar alojamiento para la documentación de Sphinx que mantiene tus documentos actualizados en todas las versiones. En conjunto, constituyen un maravilloso conjunto de herramientas que los desarrolladores y escritores técnicos pueden usar para crear la documentación de usuario que sea más adecuada para los usuarios finales.

Sphinx incluye compatibilidad para traducir la documentación a varios idiomas. Admite el control de versiones que se usará para administrar la documentación. A diferencia de la wiki actual, en la que cualquiera 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 versiones 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 Read the Docs son utilizados por una lista de otras comunidades y proyectos excelentes, como ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, etc., y es una excelente herramienta para usar en la nueva documentación para usuarios de VLC.

No solo 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. Puedes encontrar la versión alojada en readthedocs 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 para usuarios 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 deben aprobarla. Esto significa que es probable que la estructura cambie después de que los mentores la revisen.

OBJETIVOS DEL PROYECTO

Reestructura la documentación.
Se actualizó la documentación para que se ajuste a las versiones modernas de VLC.
Migra la documentación del usuario a Gitlab con 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 entender.
Configura la traducción con la internacionalización de Sphinx.
Haz que la documentación esté orientada a la comunidad para que los usuarios puedan informar o resolver cualquier problema que encuentren mientras la leen.

¿POR QUÉ ESTE PROYECTO?

Siempre tuve la convicción de que escribir código, resolver problemas y crear software alcanza su máximo potencial cuando también tienes la capacidad de concientizar a los demás sobre ello a través de la escritura. En lo personal, siempre me han fascinado los esfuerzos que realiza la comunidad de VideoLAN para crear soluciones de software libre para multimedia. Cuando era niño, el reproductor multimedia VLC siempre fue el software que usaba cuando escuchaba música o miraba una película porque era muy alto 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 porque:

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 no será un problema realizar comandos en Gitab. Además, me motiva trabajar en proyectos que creen valor para las personas.
Creo que si quieres que alguien haga algo de la manera más eficiente posible, debes documentarlo. Cuando documentas tus procesos, garantizas la eficiencia, la coherencia y la tranquilidad de todas las partes involucradas.
Conozco las necesidades de los usuarios de VLC porque soy uno de ellos. Esto permitirá escribir la documentación de tal manera que todos los demás usuarios del mundo la entiendan a primera vista.