L2: Practica 0_2
- Tiempo: 2h
- Fecha: Lunes, 7 de Febrero de 2022
-
Objetivos de la sesión:
- Puesta en marcha de la wiki del repo de prácticas
- Practicar con Markdown
- Hacer la página de la wiki de la práctica 0
- Seguir practicando con VSCode y Github
- Introducción
- Enunciado práctica 0 (ESPECIFICACIONES)
- Elementos de un repositorio
- Creando la wiki
- Editando una página de la wiki
- Historial de la wiki
- Colocando una imagen de prueba
- Creando la plantilla de la barra lateral
- Creando la plantilla para la práctica P0
- Actividades NO guiadas
- Resumen de tareas a realizar
- Conclusiones
- Autores
- Licencia
- Enlaces
Cualquier proyecto realizado en ingeniería tiene una parte muy importante: la documentación. La mayoría de las veces, la realizacion de una buena documentación requiere más tiempo que el propio proyecto
En un primer nivel diferenciamos dos tipos de documentación:
-
Documentación técnica (Memoria del proyecto). Es información técnica, escrita por Ingenieros para Ingenieros. Se deben incluir todos los detalles técnicos necesarios para que otro ingeniero pueda entender nuestro trabajo y continuarlo
-
Manual de usuario. Cómo se usa lo que hemos generado en el proyecto. Aquí por usuario nos referimos a la que persona que va a usar nuestro diseño. No para modificarlo, entenderlo o ampliarlo, sino sólo para usarlo. Este usuario puede a su ver ser otro ingeniero o persona que requiera de conocimientos técnicos. Por ejemplo, en el manual de usuario de un servidor web indicaremos cómo se hace para arrancarlo, paralo, configurarlo, etc.
En un segundo nivel está la documentación que amplía lo anterior con la idea de formación. Esta es una documentación más extensa y más elaborada para que otros aprendan: Tutoriales, vídeos, demostraciones, ejemplos de uso... ¡La documentación es infinita!
Cada práctica de LTAW es un mini-proyecto. Para poder realizarlo primero tendremos que aprender cosas, practicarlas, asimilarlas y después implementar el proyecto pedido. Y por supuesto, como todo proyecto, tendremos que documentarlo
La documentación la realizaremos en la wiki de github asociada a nuestro repositorio de prácticas (LTAW-Practicas), y la escribiremos usando Markdown
En esta práctica 0-2 crearemos el esqueleto de nuestra wiki donde documentaremos cada una de las prácticas del curso. Sólo mirando esta wiki, cualquier ingeniero deberá entender vuestras prácticas, y ponerlas en marcha
Crea la wiki asociada a tu repositorio LTAW-Practicas. La página principal de esta wiki deberá contener la siguiente información, divida en apartados independientes:
- Portada o cabecera general (para saber en qué lugar de la wiki estamos)
- Índice de contenido: Enlaces a las diferentes secciones de la página principal
- Breve CV sobre ti (no pongas datos personales), pero sí puedes poner enlaces a tus redes sociales u otras páginas personales
- Descripción técnica del equipo que estás usando para la realización de las prácticas: Hardware, S.O, periféricos...
- Panel lateral índice, desde el que se irán poniendo los enlaces a las documentaciones de las prácticas
- Enlaces: Recopilación de enlaces externos que consideres imporatntes, relacionados con la información contenida en esta página principal
- Licencia: Para indicar las condiciones de uso del material incluido en la documentación. (Ej. yo en mis documentaciones utilizo la licencia libre CC-By-SA)
La wiki se hará usando Markdown. La página principal deberá incluir los siguientes elementos de Markdown:
- Listas de items
- Encabezados al menos a 2 niveles
- Imágenes
- Enlaces
- Texto en negrita y en cursiva
- Al menos una tabla
Las imágenes usadas en la documentación de cada prácticas se situarán en la carpeta wiki que se creará dentro de cada práctica. Así, las imágenes a utilizar en la página principal de la wiki (que estamos creando en la práctica 0), estarán alojadas en la carpeta P0/wiki. Las de la práctica 1 estarán en P1/wiki, las de la 2 en P2/wiki, etc...
TODAS las imágenes usadas deben estar alojadas en tu repositorio
Si nos vamos a nuestro repositorio LTAW-Practicas, vemos las carpetas y ficheros disponibles. Pero en un repositorio de github hay más elementos que nos ayudan en nuestro proyecto. Los demos en la parte superior. Por defecto está activada la pestaña Code que nos da acceso a los ficheros
Pero existen más elementos:
- Issues: Comentarios o problemas detectados por otras personas que usado mi proyecto. Se utilizan para dejar constancia de errores (bug), nuevas características a implementar, etc.
- Pull request: Contribuciones a tu proyecto. El propieratorio del repositorio evalúa estas aportaciones, y decide si integrarlas (Merge) o no en el proyecto principal
- Actions: Automatización de tareas en el repo. Por ejemplo, cada vez que se hace un commit se puede configurar para que se analicen los ficheros aportados y comprobar si son correctos o tienen errores
- Project: Herramientas para planificar y organizar mejor tu proyecto
- Wiki: Documentación de tu proyecto
- Security: Políticas de seguridad
- nsights: Estadísticas de tu proyectos
En las prácticas de LTAW sólo utilizaremos la pestaña de Código (Code) y la de documentación (Wiki)
Pinchamos en la pestaña Wiki del repositorio de prácticas. Nos aparecerá una pantalla como la siguiente:
Por defecto la wiki está desactivada, y sin ninguna página. Para activarla pinchamos el botón verde Create the First page:
Ya podemos introducir los datos de la nueva página. El título que tiene por defecto es Home. Lo podemos cambiar al que más nos guste (página principal, documentación, etc...)
Por defecto la página está configurada para admitir markdown, que es el que usaremos, pero son válidos otros formatos. En la parte central es donde introducimos el texto. Por defecto se ha inicializado con el mensaje Welcome to the LTAW-Practicas wiki!
En la parte inferior podemos añadir (opcionalmente) comentarios a los cambios realizados. Pinchamos en el botón Save Page para crear y almacenar la página
Nos aparece el aspecto actual de la página. En la parte superior del navegador tenemos la URL completa de nuestra página principal de la wiki. Esta es la dirección que utilizaremos para dar acceso directo a otras personas a nuestra documentación
La dirección de la wiki de mi repositorio de ejemplo es: https://github.com/Obijuan/LTAW-Practicas/wiki
En la parte superior derecha vemos que pone un "1" al lado de Pages. Esto nos indica que actualmente la wiki contiene sólo 1 página. Es la que acabamos de crear
Para modificar una página de la wiki pinchamos en el botón superior derecho que pone Edit. Vamos a editar nuestra página principal:
Al apretar el botón de EDIT entramos en el modo edición y podemos añadir más textos. Por defecto estamos en la pestaña que pone Write: modo de escritura
En cualquier momento podemos pinchar en la pestaña Preview para ver una previsualización del texto markdown actual. Como de momento sólo hemos introducido texto normal, no notaremos mucha diferencia (salvo que en el modo de previsualización NO nos permite escribir)
Volvemos a la pestaña Write para continuar escribiendo. Vamos a escribir un texto en Negrita. Ya hemos visto en la clase de teoría que para resaltar un texto en negrita utilizamos los dos asterioscos colocados delante y detrás de la frase a convertir en negrita: **Texto en negrita**
Github nos ofrece la posiblidad de hacerlo a través de la interfaz web, seleccionando el texto y pinchando en el botón B. Nos añade automáticamente los dos asteriscos. En esta animación se muestra el proceso: Se añade el texto en negrita, se previualiza y se vuelve al modo write:
En la barra de formato tenemos más opciones: encabezados (h1, h2, h3), itálica, enlace, imágenes...
Una vez terminada la edición, pinchamos en el botón de Save Page. Este es el aspecto actual de nuestra wiki:
Debajo del título (Home en mi caso) nos aparece el número de ediciones que hemos realizado hasta el momento: 2. Si pinchamos en ese enlace vemos el historial de la wiki: todos los cambios que se han realizado hasta llegar a la versión actual
En la izquierda están los comentarios de los cambios (por defecto, nos añade un nombre si nosotros no hemos escrito ningún comentario). En la derecha aparece un código que enlaza a la wiki que había en esa versión. Vamos a pinchar para ver cómo estaba:
En la URL que aparece en el navegador podemos ver si estamos accediendo a la última versión o bien a alguna anterior. Por ejemplo, la URL de la primera versión es:
https://github.com/Obijuan/LTAW-Practicas/wiki/Home/e4815986f0b199b165812dd688b41f90577bc94b
Mientras que la última versión de la página principal estará siempre en esta URL:
https://github.com/Obijuan/LTAW-Practicas/wiki
Las imágenes en la wiki se añaden en dos pasos:
- Paso 1: Subir la imagen a tu repositorio
- Paso 2: Enlazar la imagen usando markdown desde la wiki
Como ejemplo de colocar una imagen en la wiki utilizaremos la que ya hemos previamente subido en el Ejercicio 2 de la Sesión L1 de laboratorio: Ejercicio2-img1.gif
El paso 1 ya está, por tanto, completado: la imagen se encuentra ya en nuestro repositorio. Nos vamos al repositorio en la web y localizamos el fichero: copiamos su URL
Ahora editamos la wiki y ponemos el enlace a la imagen utilizando la notación markdown (también podemos usar la barra de formato)
Y así es como queda la wiki de momento
Nuestra wiki, según las indicaciones de las ESPECIFICACIONES de la práctica 0, deberá tener un panel lateral índice. Para crear el panel lateral pinchamos en la opción Add a custom sidebar situado en la parte derecha de la wiki:
La barra lateral es otra página de la wiki, que se edita exactamente igual que el resto de páginas. En la barra lateral deberemos colocar enlaces a las páginas de la documentación de las diferentes prácticas. Como de momento no las tenemos hechas, simplemente pondremos la plantilla con los nombres, sin añadir los enlaces todavía:
En la parte superior pondremos un enlace a la página principal (Se deja indicado, pero lo debes hacer tú, es parte de la práctica)
Grabamos la página. Así es como nos está quedando:
¡¡Ya tenemos todos los conocimientos necesarios para realizar la página principal indicada en las Especificaciones!!
Vamos a dejar indicado en el borrador de la página principal TODO lo que nos indican las ESPECIFICACIONES que debemos incluir. TAmbién aprovechamos y borramos el gif animado, que lo pusimos para aprender a meter imágenes, pero que NO forma parte de la documentación de nuestras prácticas
Editamos la página principal y hacemos copy&paste de las especificaciones, y las ponemos como una lista de items. La barra lateral ya está hecha (a falta de los enlaces) por lo que no la ponemos
Guardamos la página. Así es como nos ha quedado el borrador:
Ya tienes todo lo necesario para completar la página principal de tu wiki. Lee las especificaciones. Entiéndelas y ponte a trabajar
- Crear una wiki en tu repositorio LTAW-Practicas
- Haz un borrador de la página principal con todo lo que debe tener (según las especificaciones)
- Haz los ejemplos de esta sesión para aprender a manejar la wiki
- ¡Haz la wiki!
Tras finalizar la práctica P0, deberías saber lo siguiente:
- Crear una wiki desde cero, asociada a tu repositorio
- Saber hacer documentos con markdown
- Manejo más fluido de VSCode para subir ficheros a tu repositorio
- Juan González-Gómez (Obijuan)
- Jose María Cañas
