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:
- 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
RESUMEN
La documentación del usuario se utiliza como un sistema de soporte 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 software o servicio. Si todo lo que necesita es un poco de instrucciones, sugerencias o truco, no todas las personas quieren comunicarse con el equipo de asistencia o esperar una respuesta por correo electrónico. La documentación del usuario simplemente hace eso. También reduce los costos de asistencia y es una identidad del estado de salud del producto y del equipo de desarrolladores.
VLC para Android se descargó más de 100 millones de veces solo en Google Play Store. VLC ofrece muchas funciones para sus puertos móviles, que van desde la reproducción de audio y video hasta la transmisión de red. Con frecuencia, las personas quieren usar estas fabulosas funciones, pero no pueden hacerlo. La búsqueda de un blog o de algún video aleatorio para este fin requiere mucho tiempo y paciencia, y la información obtenida no es auténtica. Actualmente, VLC aloja la documentación del usuario de VLC para Android en la página de wiki y proporciona menos o ninguna descripción de estas funciones. Además, las páginas de wiki se actualizaron por última vez en marzo de 2019. El proyecto actual proporcionará nueva documentación para usuarios con un diseño moderno y mayor facilidad de uso para el puerto Android.
SITUACIÓN ACTUAL
Las páginas de wiki están completamente desactualizadas y contienen mucha menos información sobre la última versión 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 características.
ANÁLISIS
-> A partir de ahora, la documentación actual es obsoleta y debe redactarse de una nueva forma 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 propósitos anteriores. O incluso en la misma documentación, dividir una función por conceptos técnicos y no técnicos crea confusión adicional. Como la mayoría de los usuarios están acostumbrados a la IU que ve o a las funciones que usan, no es fácil para todos decidir si algo es técnico o no. Así que deberíamos simplificarles esto.
-> La mayoría de los usuarios intentarán obtener información a través de su smartphone y descansar mediante una computadora de escritorio u otros dispositivos. Por lo tanto, la documentación debe poder adaptarse fácilmente a cada tamaño de pantalla. No debe crear confusión en cuanto a la navegación.
-> No todas las funciones de la versión de escritorio 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 la aplicación para computadoras de escritorio lleva mucho más tiempo en desarrollo y ha alcanzado una especie de estado de saturación; en cambio, el puerto móvil es relativamente nuevo y aún está en desarrollo. Aparte de eso, si bien los dispositivos móviles actuales son cada vez más potentes, existe una restricción obvia en cuanto al tipo de función 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 convertir la documentación en función de las funciones.
BASADOS EN EL ANÁLISIS, PROPIO 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 lee el tema de Documentos. Usar el mismo para el puerto de Android nos ayudará de las siguientes maneras: -> Combinar fácilmente la documentación. -> Está optimizado para todos los tamaños de pantalla. -> Experiencia fluida al navegar a la Documentación del usuario de Android a través de la documentación para computadoras de escritorio
- Separar los capítulos, secciones y subsecciones según su posición relativa en la aplicación. Por ejemplo, el modo fondo/PIP se encuentra en Más -> Configuración-> Video, por lo que la estructura del capítulo será
- Más
- |__Configuración
- | |__Biblioteca multimedia
- | |__Video -->Modo de segundo plano/PIP
- : -> Este enfoque mejorará la facilidad de acceso, ya que los usuarios podrán navegar fácilmente hasta la parte que necesitan ayuda comparándola con la ubicación relativa en la aplicación. Para cada función, podemos separar partes técnicas y no técnicas. Primero, escribiremos una descripción sencilla no técnica y, luego, destacaremos o etiquetaremos las partes técnicas de la misma función, si las hubiera, justo debajo de ella. Esto puede generar cierta repetición, pero garantizará una experiencia fluida de la mayoría no técnica. Esto también será útil en el futuro, ya que aumentará la capacidad de mantenimiento. Como la aplicación alcanzará el estado de saturación, es probable que la IU relativa no cambie demasiado en el futuro, si se agrega o quita una nueva función, simplemente podemos refactorizar la sección. En caso de que se modifique toda la IU, podemos reorganizar las secciones o los capítulos o reestructurar todo el documento. Cualquiera sea el caso, debemos modificar toda la documentación porque se deberá reemplazar la captura de pantalla para que coincida con la IU actual. Aquí encontrará una demostración en funcionamiento : https://avinal.gitlab.io/vlc-android-docs/
Cada sección de la documentación deberá consistir en una captura de pantalla etiquetada , una descripción de la función, una parte más técnica (si la hubiera) y sugerencias y trucos para la función.
-> Desarrollar esta documentación para el usuario de forma independiente desde el escritorio nos ayudará a combinarla en unos pocos pasos sin afectar la documentación actual ni verse afectada por ella durante el desarrollo. Propongo que coloques toda esta documentación en la sección de Android de la documentación de escritorio una vez que se haya desarrollado y, luego, crees un vínculo permanente de la documentación de VLC para Android.
-> Es posible que más mejoras incluyan rediseñar la página de inicio de la documentación del usuario para computadoras de escritorio para que los usuarios puedan elegir directamente su SO favorito y redireccionarlo a la documentación del SO que eligió. Como la documentación para usuarios de VLC en Windows, MacOS y Linux ya está bien diseñada y conversada, podemos elegir opciones de Windows/MacOS/Linux o Android o iOS. Esto dará como resultado una documentación del usuario bien separada pero unificada con un solo vínculo para usar en todos los puertos.
¿POR QUÉ ES MEJOR LA DOCUMENTACIÓN DE USUARIO PROPUESTA? Esta documentación propuesta para el usuario se estructura 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 conocimientos tecnológicos para maximizar la facilidad de uso y la experiencia del usuario final. Esto también es fácil de mantener, ya que ya no es necesario mantener documentación de usuario individual para cada puerto.
¿POR QUÉ SOY LA PERSONA ADECUADA PARA ESTE PROYECTO? -> Hace 2 años que estuve escribiendo códigos y, a menudo, necesito revisar la documentación de la API de ciertas bibliotecas o algún software, o incluso documentar mi propio código. Así que sé exactamente qué quieren ver las personas en la documentación, qué problemas enfrentan y cómo abordan el proceso para obtener ayuda. Podré aplicar la misma experiencia para escribir una documentación coherente y fácil de leer.
-> Escribí temas técnicos de forma activa en Quora, Stack Overflow y otras plataformas. Sé cómo explicar las cosas de manera atractiva y fácil de entender.
-> VLC para Android es una herramienta poderosa y muy famosa, pero la mayoría de sus funciones son desconocidas o no hay ayuda disponible. Utilizo VLC en plataformas móviles y de escritorio desde hace muchos años y sé qué problemas pueden enfrentar los usuarios. Al combinar todos mis conocimientos y experiencia, puedo garantizar una gran documentación.