Los tutoriales ayudan a los usuarios a obtener información sobre los productos y a resolver problemas reales, guiándolos a lo largo de todo el flujo de trabajo para realizar una tarea. Los tutoriales tienen un tono más conversacional que otros tipos de contenido. Un tutorial se siente como una conversación entre desarrolladores, aunque esté accesible para lectores con diversos conocimientos técnicos. Los productos con tutoriales deben tener ya una guía de inicio rápido. Para flujos de trabajo más pequeños, usa el modelo de guía de inicio rápido.
Los tutoriales son para personas que desean obtener asesoramiento experto y una explicación detallada de los procedimientos recomendados para su problema. Los tutoriales también ayudan a las personas que han implementado soluciones similares en el pasado con otros productos a usar GitHub. Los tutoriales pueden ayudar también a los usuarios a validar si la solución es adecuada para sus necesidades.
En conjunto, nos referimos a los tutoriales y guías de inicio rápido como "guías" en el sitio. En las páginas de aterrizaje de /guides, se incluyen tutoriales, guías de inicio rápido y determinados artículos de procedimientos en la lista de guías de un conjunto de documentos.
Cómo escribir un tutorial
Para obtener la plantilla del tutorial, consulte "Plantillas".
Contenido de los tutoriales:
- Introducción
- Deja clara la audiencia.
- Indica claramente los requisitos y conocimientos previos necesarios.
- Indica lo que el usuario logrará o creará.
- Incluye un ejemplo de un proyecto correcto.
- No incluye la cantidad de tiempo que se prevé que puede tardar alguien en realizar la tarea. Esto depende del nivel de experiencia de la persona que realiza el tutorial.
- Secciones de procedimientos
- En función de la audiencia del tutorial, los pasos pueden ser menos explícitos y formales que los que se usan en el contenido de procedimientos. No es necesario usar contenido reutilizable para elaborar estos pasos si la audiencia no requiere ese nivel de detalle.
- Usa: "From your profile, click Settings, and then click Developer settings".
- Evita: In the upper-right corner of any page, click your profile photo, then click Settings. En la barra lateral izquierda, haga clic en Developer settings (Configuración del desarrollador).
- Incluye vínculos a otros artículos o recursos en lugar de replicarlos, para no interrumpir el flujo de información en el tutorial.
- Proporciona indicaciones visuales. Usa bastantes bloques de código y capturas de pantalla para asegurarte de que los usuarios realizan las acciones correctas.
- Proporciona ejemplos reales.
- Por ejemplo, no le digas al usuario "Enter a commit message". En lugar de esto, muéstrale un ejemplo de mensaje de confirmación apropiado que coincida con los pasos anteriores.
- En función de la audiencia del tutorial, los pasos pueden ser menos explícitos y formales que los que se usan en el contenido de procedimientos. No es necesario usar contenido reutilizable para elaborar estos pasos si la audiencia no requiere ese nivel de detalle.
- Solución de problemas
- Indica lo que puede salir mal en la tarea y enumera algunos problemas comunes que pueden surgir con soluciones.
- Conclusión
- Revisa lo que se ha logrado o creado. Vuelve al proyecto proporcionado en la introducción como ejemplo de un proyecto correcto.
- Pasos siguientes
- Incluye 2 o 3 pasos siguientes que el usuario puede realizar después de completar el tutorial. Incluye vínculos a otra información relacionada, como:
- Proyectos de GitHub que ilustran los conceptos tratados.
- Información relevante de docs.github.com.
- Contenido relevante de GitHub Skills.
- Charlas publicadas, entradas de blog o publicaciones en foros de comunidades de Hubbers que sean relevantes.
- Incluye 2 o 3 pasos siguientes que el usuario puede realizar después de completar el tutorial. Incluye vínculos a otra información relacionada, como:
Directrices para los títulos de los tutoriales
- Sigue las directrices para los títulos de los artículos de procedimientos.
- No uses "tutorial" ni "guide" en el título.
Ejemplos de tutoriales
Tutoriales:
- Agregar etiquetas a las propuestas
- Instalar un certificado de Apple en ejecutores de macOS para el desarrollo de Xcode
Guías de lenguajes y marcos: