Texto utilizado hasta ahora en la primera sección de tutoriales de TYPO3:
«Este documento es un tutorial. Los tutoriales están diseñados para ser instrucciones paso a paso creadas específicamente para guiar a un principiante a través de una tarea en particular de principio a fin. Para facilitar el aprendizaje efectivo, los tutoriales proporcionan ejemplos para ilustrar las materias que cubren. Además, los tutoriales proporcionan orientación sobre cómo evitar errores comunes y destacan conceptos clave que deben recordarse para referencia futura.»
Al mirar la literatura mencionada a continuación, debemos considerar los siguientes puntos clave:
- un tutorial es una lección, orientada al aprendizaje, que muestra los pasos para completar algo, haciendo que el lector sea más conocedor
- el lector debe lograr algo significativo y experimentar el éxito, encontrarlo factible y agradable, mejorar la competencia, ganar confianza y querer hacerlo de nuevo.
- concéntrese en el conocimiento práctico, no en el conocimiento teórico. Aprenda un nuevo oficio o habilidad, concéntrese en aprender haciendo
Pautas:
- permitir que el usuario aprenda haciendo,
- pasar de simple a complejo
- Iniciar al usuario
- está bien mostrar los pasos que el principiante entiende mejor. las «mejores prácticas» pueden ser algo diferente. Cómo lo haría un usuario experimentado puede ser algo diferente.
- El objetivo es que el lector comience, no que llegue a un destino final.
- ¡Asegúrate de que tu tutorial funciona!
- inspire la confianza del principiante: en el software, en el tutorial, el tutor y, por supuesto, en su propia capacidad para lograr lo que se les pide.
- Asegúrese de que el usuario vea los resultados inmediatamente
- La conclusión de cada sección de un tutorial, o el tutorial en su conjunto, debe ser un logro significativo.
- Su tutorial debe ser repetible de forma fiable.
- Concéntrese en pasos concretos, no en conceptos abstractos. La tentación de introducir la abstracción es enorme: resistir!
- Proporcione la explicación mínima necesaria
- Concéntrese solo en los pasos que debe seguir el usuario
Literatura¶
- Ubuntu: Cómo escribir un tutorial
- Daniele Procida: «Lo que nadie te dice sobre la documentación (19 de mayo de 2017) – Una muy buena entrada de blog sobre diferentes tipos de manuales.