Proyecto de VLC

En esta página, se incluyen 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
Redactor técnico:
Avii
Nombre del proyecto:
Crea la documentación del usuario de VLC para un puerto móvil (Android)
Duración del proyecto:
Duración estándar (3 meses)

Project description

ABSTRACT

La documentación para el usuario se usa como un sistema de asistencia estático para ayudar a los usuarios finales. Proporciona información técnica y no técnica sobre un producto o servicio. Ayuda a los usuarios a aprender a usar el software o el servicio. No todas las personas quieren comunicarse con el equipo de asistencia ni esperar una respuesta por correo electrónico si todo lo que necesitan es una pequeña dirección, sugerencias o trucos. La documentación para el usuario hace exactamente eso. También reduce los costos de asistencia y es una identidad del estado del producto y del equipo de desarrolladores.

VLC para Android se descargó más de 100 millones de veces solo desde Google Play Store. VLC proporciona muchas funciones para sus puertos para dispositivos móviles, que van desde la reproducción de audio y video hasta la transmisión de red. A menudo, las personas quieren usar estas funciones increíbles, pero no pueden hacerlo. Buscar un blog o un video aleatorio para esto requiere mucho tiempo y paciencia, y, aun así, no hay autenticidad en la información obtenida. Actualmente, VLC aloja la documentación del usuario de VLC para Android en la página de la wiki y proporciona menos o ninguna descripción de estas funciones. Además, las páginas de la wiki se actualizaron por última vez en marzo de 2019. El proyecto actual proporcionará una nueva documentación para el usuario con un diseño moderno y mayor facilidad de uso para el puerto de Android.

SITUACIÓN ACTUAL

Las páginas de la wiki están completamente desactualizadas y contienen muy poca información sobre la versión más reciente de VLC. Además, no son fáciles de navegar. No hay una opción visible para leer la documentación en otro idioma que no sea inglés. No contiene descripciones de las funciones.

ANÁLISIS

-> A partir de ahora, la documentación actual está obsoleta y debe escribirse de una manera nueva y con una plataforma y herramientas diferentes.

-> La mayoría de los usuarios de Android tienen poco o ningún conocimiento técnico. Sin embargo, hay personas que necesitan más información técnica sobre una función. No es una buena idea escribir y mantener dos documentos separados para cada uno de los fines anteriores. Incluso en la misma documentación, dividir una función en función de si es técnica o no crea más confusión. Como la mayoría de los usuarios están acostumbrados a la IU que ven o a las funciones que usan, no es fácil para todos decidir si algo es técnico o no. Por lo tanto, queremos simplificarles este proceso.

-> La mayoría de los usuarios intentarán obtener información a través de su smartphone y el resto a través de computadoras de escritorio o de otros dispositivos. Por lo tanto, la documentación debería poder adaptarse fácilmente a todos los tamaños de pantalla. No debe generar confusión sobre la navegación.

-> No todas las funciones de la versión para computadoras están disponibles en el puerto de Android y, si están disponibles, no funcionan de la misma manera en ambos puertos. Esto se debe a que las aplicaciones para computadoras de escritorio llevan mucho más tiempo en desarrollo y han alcanzado un estado de saturación. En cambio, el puerto para dispositivos móviles es relativamente nuevo y aún está en desarrollo. Aparte de eso, aunque hoy en día los dispositivos móviles se están volviendo muy potentes, hay una restricción obvia en el tipo de funciones que podemos incorporar, principalmente debido a la demanda del usuario final. Tener una función que nadie usa es un desperdicio de recursos de desarrollo. Por lo tanto, no se recomienda comparar ambas documentaciones en función de las funciones.

EN FUNCIÓN DEL ANÁLISIS ANTERIOR, TE PROPONGO LO SIGUIENTE. 1. A partir de ahora, la documentación para usuarios de computadoras de escritorio usa el generador de documentación de Sphinx y el tema de Read the Docs. Usar lo mismo para el puerto de Android nos ayudará de las siguientes maneras: -> Combinación sencilla de ambas documentaciones. -> Está optimizado para todos los tamaños de pantalla. -> Experiencia fluida al navegar a la documentación para usuarios de Android a través de la documentación de escritorio

  1. Separar los capítulos, las secciones y las subsecciones según su posición relativa en la aplicación Por ejemplo, el modo en segundo plano o PiP se encuentra en Más -> Configuración -> Video, por lo que la estructura de capítulos será
    Más
    |__Settings
    | |__Media Library
    | |__Video --> Modo de segundo plano/PIP
    : -> Este enfoque mejorará la facilidad de acceso, ya que los usuarios podrán navegar fácilmente a la parte en la que necesitan ayuda comparándola con la ubicación relativa en la aplicación. Para cada una de las funciones, podemos separar las partes técnicas y no técnicas. Primero escribiremos una descripción no técnica sencilla y luego destacaremos o etiquetaremos las partes técnicas de la misma función, si las hay, justo debajo. Esto puede generar algunas repeticiones, pero garantizará una experiencia fluida para la mayoría de los usuarios no técnicos. Esto también ayudará en el futuro, ya que aumentará la capacidad de mantenimiento. Como la aplicación alcanzará el estado de saturación, es poco probable que la IU relativa cambie mucho, por lo que en el futuro, si se agrega o se quita una nueva función, simplemente debemos refactorizar la sección. En caso de que se cambie toda la IU, podemos reorganizar las secciones o los capítulos, o bien reestructurar todo el documento. En cualquier caso, debemos modificar toda la documentación porque se deberá reemplazar la captura de pantalla para que coincida con la IU actual. Aquí se aloja una demostración en funcionamiento : https://avinal.gitlab.io/vlc-android-docs/

  2. Cada sección de la documentación debe incluir una captura de pantalla etiquetada, una descripción de la función, una parte más técnica, si corresponde, además de sugerencias y trucos para la función.

-> Desarrollar de forma independiente esta documentación para el usuario desde la computadora de escritorio nos ayudará a combinar ambas en solo unos pasos sin afectar la documentación actual ni ser afectados por ella durante el desarrollo. Propongo colocar toda esta documentación en la sección de Android de la documentación para computadoras de escritorio una vez que se desarrolle y, luego, crear un vínculo permanente para la documentación de VLC para Android.

-> Entre otras mejoras, se podría rediseñar la página de inicio de la documentación para usuarios de computadoras de escritorio para permitir que los usuarios elijan directamente su SO favorito y, luego, redireccionarlos a la documentación del SO elegido. Dado que la documentación para el usuario de VLC para Windows, macOS y Linux ya está bien diseñada y conversada, podemos incluir opciones para elegir entre Windows/MacOS/Linux o Android o iOS. Esto generará una documentación del usuario bien separada, pero unificada, con un solo vínculo para usar en todos los puertos.

¿POR QUÉ MI PROPUESTA DE DOCUMENTACIÓN DE USUARIO ES MEJOR? Esta documentación del usuario propuesta está estructurada en función de los patrones comunes que sigue el usuario final para obtener ayuda. La documentación combina todas las características requeridas, p.ej., simplicidad, claridad, apariencia y conocimiento tecnológico para maximizar la facilidad de uso y la experiencia del usuario final. Esto también se puede mantener fácilmente, ya que ya no es necesario mantener la documentación de los usuarios individuales para cada puerto.

¿POR QUÉ SOY LA PERSONA ADECUADA PARA ESTE PROYECTO? -> Tengo 2 años escribiendo códigos y, a menudo, necesito revisar la documentación de la API para ciertas bibliotecas o algún software, o incluso documentar mi propio código. Por lo tanto, sé exactamente qué quieren ver las personas en la documentación, qué problema enfrentan y cómo se acercan para obtener ayuda. Podré aplicar la misma experiencia para escribir una documentación coherente y fácil de leer.

-> Escribo material técnico de forma activa en Quora, Stack Overflow y varias otras plataformas. Sé explicar las cosas de un modo que sea atractivo y que la gente pueda entenderlas fácilmente.

-> VLC para Android es una herramienta potente y muy famosa, pero la mayoría de sus funciones son desconocidas o no hay ayuda disponible. Uso VLC en plataformas para computadoras y dispositivos móviles desde hace muchos años y sé los problemas que puede tener un usuario. Combinando todo mi conocimiento y experiencia, puedo asegurarte una gran documentación.