Appearance
P1. Documentación del módulo
Escenario
Durante el módulo de Sistemas informáticos se realizarán diferentes actividades y prácticas relacionadas con la instalación, configuración, administración y utilización de sistemas informáticos.
El trabajo realizado deberá quedar recogido en una documentación técnica personal, organizada por unidades didácticas y publicada en Internet.
En esta práctica se creará la infraestructura necesaria para elaborar esta documentación utilizando Markdown, Visual Studio Code, Git, GitHub y GitHub Pages.
La práctica comenzará durante la UD1, pero el repositorio creado se utilizará durante todo el módulo. A medida que se realicen nuevas actividades y prácticas, su documentación se incorporará al mismo proyecto.
Práctica incremental
Esta práctica no se completa en una única sesión.
La documentación se irá ampliando durante el curso con las actividades y prácticas realizadas en las diferentes unidades didácticas.
Objetivos
El objetivo es crear y mantener un sitio de documentación técnica que permita:
- organizar la documentación del módulo;
- documentar las actividades realizadas;
- utilizar Markdown para estructurar la información;
- gestionar archivos y directorios desde la terminal;
- trabajar con Visual Studio Code;
- mantener un historial de cambios mediante Git;
- almacenar el proyecto en GitHub;
- publicar la documentación mediante GitHub Pages;
- localizar y utilizar documentación técnica;
- mantener actualizada la documentación durante el curso.
Repositorio
El proyecto se almacenará en un repositorio de la organización de GitHub:
iesgrao-daw1-si-2627
El repositorio será inicialmente privado y utilizará la nomenclatura usuario-docs, donde usuario se corresponde con el nombre de usuario de la identidad digital del alumno.
Ejemplo
La alumna ficticia Laura Martínez García, con la identidad digital
laumargar@alu.edu.gva.es, crearía el repositoriolaumargar-docs.
Estructura inicial
La documentación deberá organizarse desde el principio teniendo en cuenta las siete unidades didácticas del módulo.
El archivo index.md actuará como índice general.
Una posible estructura inicial será:
text
identidad_digital-docs/
├── index.md
├── ud1/
├── ud2/
├── ud3/
├── ud4/
├── ud5/
├── ud6/
└── ud7/Esta estructura podrá ampliarse posteriormente según las necesidades de las diferentes prácticas.
Índice
El archivo index.md deberá contener el título de la documentación y un índice con las siete unidades didácticas.
Por ejemplo:
markdown
# Sistemas informáticos
## UD1. Documentación técnica
## UD2. Instalación de sistemas operativos
## UD3. Gestión de la información
## UD4. Configuración de sistemas operativos
## UD5. Sistemas en red
## UD6. Gestión de recursos en red
## UD7. Aplicaciones de propósito generalDentro de cada unidad se irán incorporando enlaces a las prácticas y actividades realizadas.
Por ejemplo:
markdown
## UD1. Documentación técnica
- [P1. Documentación del módulo](ud1/p1.md)El índice deberá mantenerse actualizado durante todo el curso.
Documentación de la UD1
Durante la UD1 se realizarán diferentes ejercicios relacionados con los contenidos estudiados.
Entre ellos se trabajará con:
- documentación técnica;
- búsqueda de documentación;
- archivos y directorios;
- Visual Studio Code;
- Markdown;
- Git;
- GitHub;
- GitHub Pages;
- comunicación y transferencia.
Los ejercicios concretos se irán indicando durante el desarrollo de la unidad.
Cada ejercicio realizado deberá incorporarse a la documentación de la UD1 siguiendo las indicaciones proporcionadas en clase.
Actividades de clase
La documentación deberá incluir tanto las actividades incluidas en los apuntes como aquellas que se planteen adicionalmente durante las clases.
Por tanto, el contenido de la práctica podrá ampliarse durante el desarrollo de la unidad.
Documentar las actividades
La documentación no consistirá únicamente en indicar que una actividad se ha realizado.
Cuando corresponda, deberá incluir elementos como:
- objetivo de la actividad;
- comandos utilizados;
- procedimientos realizados;
- resultados obtenidos;
- capturas de pantalla;
- archivos creados;
- enlaces utilizados;
- documentación consultada.
La información necesaria dependerá del tipo de actividad realizada.
Por ejemplo, para documentar un procedimiento realizado desde la terminal podrán incluirse los comandos utilizados:
bash
mkdir documentation
cd documentation
touch README.mdy las capturas necesarias para comprobar el resultado.
Capturas de pantalla
Las capturas se almacenarán dentro del propio proyecto y se incorporarán a los documentos mediante Markdown.
Por ejemplo:
text
ud1/
├── images/
│ ├── terminal-01.png
│ └── github-01.png
└── p1.mdUna imagen podrá incluirse mediante:
markdown
Las capturas deberán:
- mostrar claramente la información relevante;
- tener un tamaño que permita leer su contenido;
- mostrar únicamente la información necesaria;
- permitir identificar al alumno cuando se solicite;
- evitar mostrar contraseñas, tokens, claves u otra información sensible.
Documentación consultada
Durante las actividades será necesario localizar información técnica para resolver diferentes tareas.
Siempre que se utilice documentación externa relevante para realizar una actividad, deberá indicarse la fuente consultada.
Por ejemplo:
markdown
## Referencias
- [Ubuntu documentation](https://documentation.ubuntu.com/)
- [Git documentation](https://git-scm.com/doc)Se priorizará la utilización de documentación oficial cuando resulte necesario comprobar una información técnica.
Control de versiones
La documentación se gestionará mediante Git.
Los cambios deberán registrarse progresivamente mediante commits relacionados con el trabajo realizado.
Por ejemplo:
text
Add initial documentation structure
Add Markdown exercises
Add Git exercises
Update GitHub documentation
Add GitHub Pages deploymentNo se deberá realizar un único commit con todo el contenido de la unidad.
El historial deberá reflejar la evolución real de la documentación.
GitHub
El repositorio local se sincronizará con el repositorio correspondiente de GitHub.
Durante el desarrollo de la práctica se utilizará el flujo habitual:
text
Modificar documentación
↓
git status
↓
git add
↓
git commit
↓
git push
↓
GitHubAntes de comenzar a trabajar desde un equipo diferente deberá comprobarse que se dispone de la versión actualizada del repositorio.
Publicación
La documentación se publicará mediante GitHub Pages siguiendo las instrucciones indicadas durante la unidad.
El sitio publicado deberá permitir acceder desde su página principal a las diferentes unidades y prácticas documentadas.
Después de cada actualización deberá comprobarse que:
- la publicación se ha realizado correctamente;
- los enlaces funcionan;
- las imágenes se muestran;
- los bloques de código son legibles;
- la estructura de la documentación es correcta.
Continuación durante el módulo
El proyecto creado en esta práctica se utilizará también en las siguientes unidades.
La documentación evolucionará progresivamente:
text
Inicio del curso
index.md
└── UD1
└── actividades y prácticas
↓
Desarrollo del módulo
index.md
├── UD1
├── UD2
├── UD3
├── UD4
├── UD5
├── UD6
└── UD7
↓
Final del curso
Documentación completa
del módulo de Sistemas informáticosAl comenzar una nueva unidad se añadirá al proyecto la documentación correspondiente y se continuará utilizando el mismo flujo de trabajo con Markdown, Git y GitHub.
La documentación es parte de la práctica
A partir de esta unidad, documentar correctamente el trabajo realizado formará parte del procedimiento habitual de las prácticas del módulo.
La documentación deberá evolucionar al mismo tiempo que se realiza el trabajo y mantenerse actualizada en el repositorio.