Uso de vídeos en GitHub Docs

Acerca de los vídeos en GitHub Docs

Es poco frecuente que se usen vídeos en GitHub Docs. Cuando son necesarios para proporcionar la mejor experiencia de usuario para un artículo, se usan junto con texto escrito. Los vídeos no reemplazan el contenido escrito. Nunca deben ser la única forma de comunicar la información, porque son más difíciles de mantener al día y no todos los usuarios pueden acceder a ellos.

Usa estas instrucciones para determinar si un vídeo es adecuado para incluirlo en un artículo o en una página de aterrizaje de la documentación.

Si agregas un vínculo a un vídeo o insertas un vídeo en GitHub Docs, agrega los metadatos del vídeo al archivo Vídeos en GitHub Docs en el repositorio github/docs.

El equipo de Docs no crea ni mantiene el contenido de los vídeos. Los vídeos son meramente complementarios para ayudar a comunicar temas importantes o complejos y se deben usar con moderación, porque no son un tipo de contenido propiedad del equipo de Docs.

Lista de comprobación para un vídeo

Usa esta lista de comprobación para determinar rápidamente si un vídeo podría ser adecuado para agregarlo a un artículo o a una página de aterrizaje.

• ¿El vídeo es la única manera de comunicar la información?
• ¿El vídeo es propiedad de GitHub?
• ¿El vídeo está bien producido? (Consulta la sección Procedimientos recomendados para más información).
• ¿El vídeo es accesible para el grupo más amplio de usuarios posible? (Consulta la sección Requisitos de accesibilidad para más información).
• ¿El vídeo dura menos de cinco minutos?
• ¿El vídeo tiene un público y un propósito específicos en la documentación? Si solo es pertinente para una característica o un producto determinado, debes crear una versión correspondiente. Consulta la sección Control de versiones para más información.

Si respondes "No" a cualquiera de estas preguntas, significa que no es adecuado agregar el vídeo a GitHub Docs.

Mantenimiento de los vídeos

Si un vídeo tiene una programación de mantenimiento o un equipo directamente responsable de auditar y actualizar el contenido si queda obsoleto, puedes incluir el vídeo sin ningún paso adicional.

Si el vídeo no tiene ninguna programación de mantenimiento, crea una incidencia con una fecha objetivo adecuada para revisar o quitar el vídeo.

Procedimientos recomendados

Usa estos procedimientos recomendados para poder determinar si un vídeo está bien producido y si tiene una calidad suficientemente alta para incluirlo en GitHub Docs.

Un buen vídeo muestra una agenda explicativa con pasos y objetivos para que cualquier usuario que lo vea sepa rápidamente lo que va a aprender. Los vídeos son demostrativos, por lo que muestran y explican los pasos pertinentes que van a llevar a cabo. Los vídeos deben ser atractivos y alentadores. Para que se los incluya en GitHub Docs, deben estar bien producidos. Un vídeo bien producido presenta pocas barreras para personas con discapacidades, tiene una narración profesional (si se trata de un vídeo narrado), imágenes claras y proviene de un origen de confianza, como GitHub o Microsoft.

Los vídeos se agrupan ampliamente en tres categorías: información general de un producto, vídeos de características y tutoriales. Estas descripciones son generalizaciones de cada tipo de vídeo. Es posible que algunos vídeos no se ajusten perfectamente a una categoría, pero de todos modos pueden ser útiles sin cumplir con las directrices exactas.

Información general de un producto

• Propósito: explicar brevemente qué es el producto, mostrar su funcionalidad principal y hacer que las personas se interesen por el producto
• Duración: menos de un minuto
• Públicos posibles: personas que quieren saber si una característica les resulta útil para alcanzar sus objetivos, personas que usan GitHub por primera vez e intentan comprender qué hacen los productos
• Ubicaciones posibles en la documentación: páginas de aterrizaje y guías

Vídeos de características

• Propósito: complementar el contenido conceptual o de procedimientos
• Duración: lo más breves posible, sin superar los cinco minutos. Dividir contenido más largo en varios vídeos más cortos y centrados
• Públicos posibles: personas que están aprendiendo sobre una característica o su uso
• Ubicaciones posibles en la documentación: guías, artículos conceptuales, artículos de procedimientos

Tutoriales

• Propósito: ayudar a los usuarios principiantes a comenzar a utilizar un producto, impulsar la adopción o explicar funcionalidades complejas
• Duración: los vídeos individuales no deben durar más de cinco minutos. Los temas complejos pueden tener una serie de vídeos más cortos distribuidos a lo largo de un artículo. En total, no pueden durar más de 15 minutos
• Públicos posibles: usuarios nuevos de características o productos
• Ubicaciones posibles: guías

Cuándo usar los vídeos

Podríamos usar vídeos en lugar de otros objetos visuales, como capturas de pantalla o diagramas, cuando lo que importa es mostrar el movimiento o los cambios de estado, como cuando algún usuario navega de una pantalla a otra o se presenta la demostración de una característica que implica el progreso a través de varios menús. Sin embargo, las capturas de pantalla o el texto pueden bastar para explicar estos procedimientos.

Los vídeos también pueden ser útiles para presentar características o productos para los que un vídeo de 30 segundos puede complementar la información que requiere varios párrafos.

Usa vídeos que expliquen el valor del procedimiento o concepto que muestran.

Cuándo no usar vídeos

No uses vídeos para las características que se actualizan con frecuencia, porque los vídeos pueden quedar desactualizados. No uses vídeos que contraigan el contenido escrito o infrinjan alguna parte de Guía de estilo. No uses vídeos que simplemente muestren una tarea sin explicar ni detallar el procedimiento. Los vídeos deben ser útiles y pertinentes, lo que incluye que se mantengan precisos a lo largo del tiempo.

Requisitos de accesibilidad

Estos son los requisitos mínimos para incluir un vídeo en GitHub Docs. Si un vídeo infringe cualquiera de estos requisitos, no se puede agregar a la documentación.

• No se permiten efectos estroboscópicos o intermitentes.
• Debe tener subtítulos. Consulta Creación de subtítulos de vídeo a continuación para más información.
• No puede haber superposición de gráficos donde aparecen los subtítulos.
• La tipografía debe ser legible.
• Toda superposición debe tener relaciones de contraste suficientes.
• Todo texto debe aparecer en la pantalla el tiempo suficiente para leerlo (el texto debe permanecer en pantalla durante más tiempo de lo que se tarda en leerlo dos veces en voz alta).
• Debe haber transcripciones descriptivas corregidas de lo que ocurre en cada escena. Consulta Creación de transcripciones de vídeo a continuación para más información.
• Los vídeos no se pueden reproducir automáticamente.

Creación de subtítulos de vídeo

Los vídeos deben tener subtítulos generados por personas antes de agregarlos al sitio de Docs. Puedes usar la tecnología de subtítulos automáticos para ayudar a crear los subtítulos, pero alguien debe revisarlos y editarlos para garantizar que son precisos. Si el servicio en el que se hospeda el vídeo tiene una herramienta de subtítulos nativa, como YouTube, puedes usarla para preparar subtítulos o crear un archivo de transcripción con el formato SRT o VTT correcto para cargarlo con el vídeo.

La creación de subtítulos forma parte del proceso de producción de vídeos a los que pueden acceder más personas, por lo que el propietario de cualquier vídeo que se agregue a GitHub Docs debe proporcionar subtítulos.

Directrices para los subtítulos

Siempre que sea posible, los subtítulos deben coincidir exactamente con las palabras que se dicen en el vídeo. No parafrasees ni trunquen subtítulos, a menos que, por restricciones de tiempo importantes, sea difícil que alguien los lea en el tiempo establecido.

Los subtítulos deben estar sincronizados para que aparezcan aproximadamente al mismo tiempo que el audio. Los subtítulos siempre estar programados para aparecer en pantalla en el momento en que el hablante empieza a hablar. Si alguien habla rápido y puede ser difícil leer los subtítulos sincronizados de manera precisa con el audio, puedes hacer que se mantengan en pantalla incluso después de que la voz deje de hablar.

Si hay varios hablantes en un vídeo, identifícalos en los subtítulos. Para ello, agrega el nombre de cada hablante (o un nombre descriptivo como Developer) antes del inicio de la oración. Por ejemplo: Jimmy: Hello.. Solo tienes que hacerlo cuando el hablante cambia y no para cada línea de diálogo. No es necesario hacerlo si las imágenes identifican claramente al hablante.

Los subtítulos deben tener una o dos líneas con no más de 32 caracteres cada una. Coloca una oración nueva en una línea nueva. Si debes cambiar de línea en mitad de una frase, hazlo en un punto lógico; por ejemplo, después de alguna coma o antes de conjunciones como and o but.

Incorporación y edición de subtítulos en YouTube

Si se trata de vídeos hospedados en YouTube, consulta Añadir subtítulos y Edita o quita subtítulos en la documentación de YouTube.

Creación de transcripciones de vídeo

Debemos tener una transcripción descriptiva de cada vídeo vinculado o insertado en la documentación. Los artículos de transcripción tienen el mismo formato que otros artículos, con texto preliminar de YAML y contenido de Markdown. Para agregar una transcripción al sitio de Docs, crea un artículo en content/video-transcripts e incluye la transcripción como texto del cuerpo del artículo. Asigna al artículo un nombre de archivo como transcript-VIDEO-NAME.md y una propiedad de texto preliminar title de Transcript - VIDEO NAME. Agrega el artículo al archivo index.md en el directorio video-transcripts.

No uses elementos reutilizables ni variables Liquid para reemplazar elementos como los nombres de producto en la transcripción. La transcripción debe ser fiel al audio del vídeo y no deberíamos cambiar ningún texto de la transcripción como resultado de actualizar una variable o elemento reutilizable después de generar el vídeo.

La creación de transcripciones forma parte del proceso de producción de vídeos a los que pueden acceder más personas, por lo que el propietario de cualquier vídeo que se agregue al sitio de Docs debe proporcionar contenido para una transcripción.

Puede usar los subtítulos como base para una transcripción. Edita los subtítulos para quitar las marcas de tiempo e incluye la información pertinente que se detalla a continuación. Una transcripción descriptiva incluye una versión de texto —tanto de la información visual como de la de audio— necesaria para comprender el contenido de un vídeo.

• Si hay varios hablantes en un vídeo, identifícalos en la transcripción.
• Si se conoces el género de un hablante, puedes usar sus pronombres preferidos al describir sus acciones. Por ejemplo: She points to the computer screen.. Si el género del hablante es desconocido o irrelevante para el objeto visual que se describe, puedes usar una opción sin marca de género..
• El formato de la transcripción debe ser con párrafos lógicos, listas y secciones. Puedes agregar encabezados en las secciones si esto ayuda a que los usuarios comprendan el contenido. Piensa en cómo alguien podría extraer información de la transcripción si no está viendo también el vídeo.
• Agrega todo texto en pantalla, los elementos visuales pertinentes y sonidos que no sean de voz que no estén incluidos en los subtítulos. Coloca estas descripciones después del texto hablado que acompaña en el vídeo. Da formato a la información visual entre corchetes. Por ejemplo, [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.].
• Agrega una propiedad product_video al texto preliminar de YAML del artículo de la transcripción. El valor de la propiedad product_video es la dirección URL de YouTube del vídeo. La dirección URL de YouTube del vídeo se mostrará como vínculo externo en el artículo de la transcripción.
• Al final de la transcripción, escribe End of transcript. e incluye un vínculo a la página de aterrizaje del producto sobre el que trata el vídeo con el patrón For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page)..

Consulta el artículo sobre la transcripción de textos con descripción de imágenes en la documentación de W3C para más ejemplos de transcripciones de audio e imágenes.

Vínculos a transcripciones de vídeos hospedados externamente

Agrega un vínculo al artículo con la transcripción de un vídeo en la descripción del vídeo en la plataforma en la que se hospeda. Para más información, consulta Edita la configuración de un vídeo en la documentación de YouTube.

Vínculos a transcripciones de vídeos insertados

En cualquier contenido con un vídeo insertado, agrega una propiedad product_video_transcript debajo de la propiedad product_video en el texto preliminar de YAML. El valor de product_video_transcript es un vínculo al artículo de transcripción en el directorio video-transcripts.

title: Example product landing page
product_video: 'https://www.youtube-nocookie.com/embed/URL'
product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE

Títulos para los vídeos

Los títulos deben ser descriptivos y seguir las directrices para títulos del modelo de contenido. Para más información, consulta Contenido de un artículo de Documentación de GitHub.

Control de versiones

Si un vídeo solo es pertinente para productos específicos de GitHub (Free, Pro y Team; GitHub Enterprise Server; y GitHub Enterprise Cloud), se deben crear versiones del vídeo para cada uno de esos productos. Usa instrucciones condicionales Liquid para crear una versión adecuada de los vídeos. Es posible que sea necesario agregar el control de versiones condicional de Liquid cuando se cree el contenido, o bien quizás sea necesario agregarlo cuando se actualice una características o una versión de GitHub Enterprise. Para obtener más información sobre las instrucciones condicionales líquidas y el control de versiones, consulta Documentación sobre el control de versiones.

Hospedaje de vídeos

Los vídeos se deben hospedar en alguna ubicación propiedad de GitHub a la que pueda acceder el equipo de Docs. Los vídeos no deber realizar un seguimiento de los usuarios ni tampoco utilizar cookies. En este momento, los vídeos de GitHub se hospedan en YouTube y se agregan a la documentación con el modo de privacidad mejorada. Para ello, cambia el dominio de la dirección URL insertada de https://www.youtube.com/VIDEO a https://www.youtube-nocookie.com/VIDEO.