Categoría: Documentación

  • Operación MONCLOA.GIT — El Ministerio de las Promesas Imposibles

    Operación MONCLOA.GIT — El Ministerio de las Promesas Imposibles

    Introducción: bienvenidos al ministerio

    El Gobierno de la República de Gitlandia acaba de crear el Ministerio de las Promesas Imposibles, una institución encargada de desarrollar un programa electoral que cambiará constantemente.

    El problema es que cada vez que un político cambia de opinión, los funcionarios sobrescriben los documentos anteriores. Nadie sabe qué prometieron ayer, quién modificó una propuesta o cuándo desapareció una medida electoral.

    El ministro de Tecnología ha decidido contratar a un administrador de sistemas para solucionar el problema: tú.

    Tu misión será poner en funcionamiento un sistema de control de versiones que permita conservar todas las promesas electorales, identificar sus modificaciones, recuperar propuestas anteriores y publicar el programa en Internet.

    A lo largo de la práctica se producirán varios incidentes: promesas incumplidas, presupuestos disparatados, borrados accidentales y hasta un intento de manipulación del programa electoral.

    Toda la actividad es ficticia. La sátira se dirige a situaciones políticas generales, sin necesidad de utilizar partidos o políticos reales.

    Objetivos de aprendizaje

    Al terminar, cada alumno deberá ser capaz de:

    1. Instalar y configurar Git desde la terminal.
    2. Crear e inicializar un repositorio local.
    3. Comprender el directorio de trabajo, el área de preparación (staging) y los commits.
    4. Añadir, modificar, eliminar y recuperar archivos.
    5. Consultar el historial y comparar versiones.
    6. Utilizar .gitignore para excluir determinados archivos.
    7. Crear y utilizar ramas individualmente.
    8. Trabajar con un repositorio remoto en GitHub.
    9. Subir, descargar y sincronizar cambios.
    10. Clonar un repositorio y continuar trabajando sobre él.

    En esta práctica cada estudiante trabaja individualmente. Las colaboraciones, los conflictos entre usuarios y las pull requests quedarán para la segunda práctica.

    Antes de comenzar: comprender Git

    Git es un sistema de control de versiones distribuido. Permite registrar el estado de los archivos de un proyecto en diferentes momentos y recuperar su historial.

    Git no es lo mismo que GitHub: Git funciona localmente y no necesita Internet. GitHub es un servicio que puede alojar repositorios remotos y facilitar el intercambio de proyectos.

    Esquema conceptual simplificado: primero se modifican archivos, después se seleccionan los cambios y finalmente se registran mediante un commit.

    Fase 1. Preparación del entorno

    Paso 1. Comprobar si Git está instalado

    Abre una terminal de tu máquina virtual Ubuntu y ejecuta:

    git --version

    Si está instalado, aparecerá algo parecido a:

    git version 2.x.x

    Si aparece command not found, instala Git:

    sudo apt update
    sudo apt install git -y

    Después, verifica nuevamente su versión.

    Pregunta para el alumno: ¿Por qué crees que Git puede funcionar sin conexión a Internet?

    Paso 2. Configurar nuestra identidad

    Cada vez que realicemos un commit, Git registrará la identidad del autor.

    Configura tu nombre y correo electrónico:

    git config --global user.name "Tu Nombre"
    git config --global user.email "tu-correo@example.com"

    Utiliza un correo propio o el correo privado que GitHub te proporcione para los commits.

    Consulta tu configuración:

    git config --global --list

    Y configura la rama inicial predeterminada:

    git config --global init.defaultBranch main

    Importante: esta configuración es global para tu usuario de Linux. No es necesario repetirla para cada proyecto.

    Paso 3. Crear nuestro espacio de trabajo

    Crearemos una carpeta donde almacenar nuestros proyectos.

    mkdir -p ~/proyectos-git
    cd ~/proyectos-git
    
    mkdir ministerio-promesas
    cd ministerio-promesas

    Comprueba dónde estás:

    pwd

    Visualiza el contenido:

    ls -la

    El directorio debería estar vacío.

    Paso 4. Inicializar un repositorio

    Ejecuta:

    git init -b main

    Acabamos de convertir una carpeta normal en un repositorio Git.

    Compruébalo:

    ls -la

    Verás una carpeta oculta llamada .git.

    Esta carpeta contiene la información necesaria para que Git pueda gestionar el repositorio: objetos, referencias, configuración e historial.

    No es necesario modificar manualmente su contenido.

    Ahora ejecuta:

    git status

    Debería aparecer un mensaje parecido a:

    On branch main
    
    No commits yet
    
    nothing to commit

    Primer reto: ¿Qué sucedería si eliminásemos la carpeta .git? ¿Desaparecerían los archivos de nuestro proyecto? ¿Y el historial?

    Fase 2. Primer programa electoral

    Paso 5. Crear el documento oficial

    El presidente de Gitlandia ha anunciado el primer programa electoral:

    «Prometemos que nadie volverá a quedarse sin batería en el móvil, que todos los lunes serán festivos y que los exámenes se resolverán por votación popular».

    Vamos a escribir estas propuestas en un archivo Markdown.

    Ejecuta:

    nano programa.md

    Introduce el siguiente contenido:

    # Programa Electoral de Gitlandia
    
    ## Elecciones Generales
    
    Presidente: Don Commit Permanente
    
    ## Promesas oficiales
    
    1. WiFi gratis en todo el país.
    2. Los lunes serán festivos.
    3. Cada ciudadano tendrá un robot asistente.
    4. Los exámenes serán voluntarios.
    5. Las impresoras funcionarán siempre.
    
    ## Lema
    
    "Prometemos hasta que se llene el disco duro".

    Guarda con Ctrl + O, pulsa Intro y cierra con Ctrl + X.

    Comprueba el contenido:

    cat programa.md

    Paso 6. Consultar el estado del repositorio

    Ejecuta:

    git status

    Aparecerá el archivo programa.md como archivo no seguido (untracked).

    Esto significa que Git todavía no está controlando sus versiones.

    Ahora ejecuta:

    git add programa.md
    git status

    El archivo aparecerá preparado para incluirse en un commit.

    Acabas de añadirlo al área de preparación, también llamada staging area.

    Paso 7. Registrar el primer commit

    Un commit es un registro de una versión del proyecto, acompañado de información sobre su autor, fecha y mensaje.

    Ejecuta:

    git commit -m "Primer programa electoral de Gitlandia"

    Consulta el historial:

    git log

    Verás una entrada con un identificador, autor, fecha y mensaje.

    También puedes obtener una versión resumida:

    git log --oneline

    Comprobación: el profesor debe poder identificar el primer commit y comprobar que el repositorio está limpio mediante git status.

    Fase 3. Primer escándalo: las promesas cambian

    Paso 8. Modificar una promesa

    El ministro de Economía acaba de descubrir que los lunes festivos son caros.

    El Gobierno ha decidido modificar la segunda promesa:

    Antes: Los lunes serán festivos.

    Después: Los lunes serán festivos únicamente si no hay trabajo pendiente.

    Edita el archivo:

    nano programa.md

    Modifica esa línea, guarda el archivo y ejecuta:

    git diff

    Git mostrará los cambios respecto de la versión preparada o registrada anteriormente.

    Normalmente, las líneas eliminadas aparecen con - y las nuevas con +.

    Ejemplo de comparación

    – 2. Los lunes serán festivos.

    + 2. Los lunes serán festivos únicamente si no hay trabajo pendiente.

    Ahora registra la modificación:

    git add programa.md
    
    git commit -m "Economía limita los lunes festivos"

    Comprueba:

    git log --oneline

    Ya deberías tener dos commits.

    Paso 9. Segunda modificación: llega la oposición

    La oposición acusa al Gobierno de hacer promesas imposibles. El presidente responde anunciando nuevas medidas.

    Añade al final de programa.md:

    ## Nuevas medidas
    
    6. Un unicornio eléctrico para cada familia.
    7. Internet gratuito incluso dentro de los túneles.
    8. Los atascos serán declarados ilegales.
    9. Se eliminarán los errores 404 por decreto.

    Antes de confirmar, ejecuta:

    git status
    git diff

    Añade el archivo al staging:

    git add programa.md

    Ahora observa qué se va a registrar:

    git diff --staged

    Finalmente:

    git commit -m "Ampliación del programa con medidas revolucionarias"

    Reto: interpreta lo que estás viendo

    Responde en tu documentación: ¿qué diferencia existe entre git diff y git diff --staged? ¿Por qué puede interesarnos seleccionar los cambios antes de confirmarlos?

    Fase 4. El presupuesto secreto

    Paso 10. Crear varios documentos

    El Ministerio comienza a tener departamentos.

    Crea la estructura:

    mkdir -p economia comunicacion secretos

    Crea un archivo de presupuesto:

    cat > economia/presupuesto.txt <<'EOF'
    PRESUPUESTO GENERAL DE GITLANDIA
    
    WiFi nacional: 500 millones
    Unicornios eléctricos: 800 millones
    Robot por ciudadano: 2000 millones
    Publicidad institucional: 9000 millones
    
    Total: pendiente de calcular
    EOF

    Ahora un comunicado oficial:

    cat > comunicacion/nota.txt <<'EOF'
    COMUNICADO DEL GOBIERNO
    
    El presupuesto está perfectamente controlado.
    Las calculadoras de la oposición están manipuladas.
    EOF

    Y un documento que no debería publicarse:

    echo "Clave ficticia de demostración: VOTO123" > secretos/claves.txt

    Paso 11. Evitar archivos innecesarios con .gitignore

    Los archivos excluidos por .gitignore no se añadirán automáticamente al control de versiones cuando todavía no están siendo seguidos.

    Crea:

    nano .gitignore

    Introduce:

    # Documentos internos ficticios
    secretos/
    
    # Archivos temporales
    *.tmp
    
    # Copias de seguridad
    *.bak
    
    # Configuraciones locales
    .env

    Comprueba:

    git status

    El archivo dentro de secretos/ no aparecerá como pendiente de seguimiento.

    Puedes verificar la regla:

    git check-ignore -v secretos/claves.txt

    Ahora registra los documentos públicos y las reglas de exclusión:

    git add .gitignore economia/ comunicacion/
    
    git status
    
    git commit -m "Creación de departamentos y presupuesto oficial"

    Advertencia: .gitignore no convierte una contraseña en segura. No debe utilizarse Git para publicar secretos. Si alguna credencial real se ha incluido en un commit, ignorarla posteriormente no elimina el secreto del historial.

    Fase 5. Crisis institucional: recuperar los errores

    Esta fase es especialmente importante: aprenderemos a solucionar problemas sin destruir nuestro trabajo.

    Paso 12. Recuperar un archivo modificado

    Un funcionario decide cambiar el presupuesto utilizando un procedimiento bastante cuestionable:

    echo "TODO EL PRESUPUESTO PARA HELADOS" > economia/presupuesto.txt

    Comprueba el resultado:

    cat economia/presupuesto.txt
    git diff

    El ministro entra en pánico.

    Necesitamos recuperar la última versión confirmada del archivo.

    Ejecuta:

    git restore economia/presupuesto.txt

    Vuelve a comprobar:

    cat economia/presupuesto.txt

    El presupuesto original debería haber regresado.

    git restore ha descartado la modificación no registrada. Si hubiésemos querido conservarla, primero tendríamos que haberla guardado en otro lugar.

    Paso 13. Recuperar un archivo eliminado

    Un nuevo ministro decide que la mejor manera de evitar las críticas es eliminar los comunicados.

    Ejecuta:

    rm comunicacion/nota.txt

    Comprueba:

    git status

    El archivo aparecerá como eliminado.

    Recupéralo:

    git restore comunicacion/nota.txt

    Comprueba que existe nuevamente:

    ls comunicacion/
    cat comunicacion/nota.txt

    Paso 14. Quitar un cambio del staging

    En esta ocasión, el funcionario ha preparado accidentalmente un cambio.

    echo "Impuesto por respirar aire premium" >> economia/presupuesto.txt
    
    git add economia/presupuesto.txt
    git status

    El archivo ya está en staging.

    Para retirarlo sin perder la modificación:

    git restore --staged economia/presupuesto.txt

    Comprueba:

    git status
    cat economia/presupuesto.txt

    La modificación continúa en el archivo, pero ya no está preparada para un commit.

    Finalmente, descarta el experimento:

    git restore economia/presupuesto.txt

    Diferencia esencial

    ComandoResultado
    git restore archivoDescarta los cambios locales no preparados en ese archivo
    git restore --staged archivoLo retira del staging, conservando el contenido
    git add archivoPrepara cambios para el próximo commit
    git commitRegistra un nuevo punto del historial

    Fase 6. La hemeroteca: Git nunca olvida

    Paso 15. Investigar el historial de promesas

    Un periodista solicita el programa electoral original para comprobar qué decía el Gobierno antes de modificar sus promesas.

    Ejecuta:

    git log --oneline

    El resultado será parecido a este (los identificadores serán diferentes):

    e3a45b1 Creación de departamentos y presupuesto oficial
    b729c81 Ampliación del programa con medidas revolucionarias
    a16d729 Economía limita los lunes festivos
    c871a93 Primer programa electoral de Gitlandia

    Cada línea representa un commit.

    Consulta los detalles del último:

    git show HEAD

    HEAD indica el commit actual de nuestra rama.

    Consulta la versión anterior:

    git show HEAD~1

    También podemos investigar los cambios de un archivo:

    git log --oneline -- programa.md

    Y comprobar cómo era en el primer commit. En nuestro caso, hemos realizado cuatro commits, por lo que:

    git show HEAD~3:programa.md

    Atención: HEAD~3 significa retroceder tres commits desde el actual, no necesariamente acceder siempre al primero. En esta práctica funciona si se ha seguido exactamente la secuencia.

    Paso 16. Comparar dos momentos de la historia

    Consulta el historial para localizar los identificadores de dos commits.

    git log --oneline

    Después ejecuta, sustituyendo los identificadores:

    git diff ID_ANTIGUO ID_NUEVO -- programa.md

    Por ejemplo, si los identificadores fueran c871a93 y b729c81:

    git diff c871a93 b729c81 -- programa.md

    Con este procedimiento puedes demostrar que el Gobierno cambió sus promesas.

    Investigación periodística

    Elabora un pequeño informe respondiendo: ¿cuál fue la promesa modificada? ¿En qué commit ocurrió? ¿Qué mensaje acompañaba al cambio? ¿Cómo puedes recuperar el contenido de la versión original sin modificar el proyecto actual?

    Fase 7. El Gobierno comete un error histórico

    Ahora vamos a ver otra de las funciones más útiles de Git: revertir un commit completo.

    Paso 17. Registrar una medida equivocada

    El presidente firma accidentalmente un decreto que establece:

    «Todos los ciudadanos deberán pagar una cuota de 100 euros por utilizar el teclado de su ordenador».

    Añade esta línea al programa electoral:

    echo "10. Impuesto de 100 euros por utilizar el teclado." >> programa.md

    Registra el cambio:

    git add programa.md
    git commit -m "Aprobado nuevo impuesto sobre los teclados"

    La medida provoca una crisis nacional. El Gobierno quiere anularla, pero conservar la evidencia histórica de que fue aprobada.

    Ejecuta:

    git revert --no-edit HEAD

    Observa el historial:

    git log --oneline

    Deberían aparecer tanto el commit que introdujo el impuesto como otro posterior que lo revierte.

    ¿Por qué es importante? Porque Git no ha borrado el commit anterior. Ha registrado una nueva operación que anula su efecto.

    Comprueba que la medida ya no aparece:

    cat programa.md

    Así queda la historia del impuesto

    No confundas git revert con git restore. El primero crea un commit que deshace otro commit; el segundo permite recuperar archivos o quitar cambios del staging sin registrar necesariamente un nuevo commit. git Documentation+1

    Fase 8. Crear una rama: el programa electoral alternativo

    Aunque todavía no vamos a trabajar en equipo, es importante comprender las ramas. Un desarrollador individual puede utilizarlas para experimentar sin modificar su versión principal.

    Paso 18. Crear el programa de la oposición

    El partido de la oposición, llamado Partido del Código Libre (PCL), propone sustituir algunas medidas por otras todavía más absurdas.

    Desde main, crea una rama:

    git switch -c oposicion

    Comprueba:

    git branch

    Debería aparecer:

      main
    * oposicion

    El asterisco identifica la rama actual.

    Ahora crea un archivo nuevo:

    cat > oposicion.md <<'EOF'
    # Programa de la oposición
    
    Partido del Código Libre
    
    1. Prohibir las reuniones que pudieron ser un correo.
    2. Obligar a que todos los políticos usen Linux.
    3. Convertir el Congreso en un servidor de Minecraft.
    4. Que los ministros aprueben un examen de informática.
    5. Sustituir los discursos por mensajes de 140 caracteres.
    EOF

    Registra el documento:

    git add oposicion.md
    
    git commit -m "Programa alternativo de la oposición"

    Comprueba:

    ls
    git log --oneline

    Paso 19. Volver al Gobierno

    Regresa a la rama principal:

    git switch main

    Lista los archivos:

    ls

    Observa que oposicion.md ya no aparece.

    Esto ocurre porque el archivo se creó y se registró en otra rama.

    Vuelve a la oposición:

    git switch oposicion

    El archivo vuelve a aparecer.

    Paso 20. Fusionar la oposición con el Gobierno

    El presidente anuncia un pacto histórico: incorporará las propuestas de la oposición al repositorio oficial.

    Regresa a la rama principal:

    git switch main

    Fusiona la rama de la oposición:

    git merge oposicion

    Comprueba:

    ls
    git log --oneline --graph --all --decorate

    El archivo oposicion.md debe aparecer en la rama principal.

    En esta situación lo normal es que Git pueda realizar una fusión de tipo fast-forward, porque main no tenía nuevos commits desde que se creó la rama.

    No siempre aparece un commit específico de fusión. Es importante que los alumnos entiendan este comportamiento.

    Puedes eliminar la rama individual una vez integrada:

    git branch -d oposicion

    El contenido fusionado no desaparece.

    Fase 9. Llega la revolución: publicar en GitHub

    Hasta este momento hemos trabajado completamente en local. El repositorio existe únicamente dentro de nuestra máquina virtual.

    Ahora vamos a publicarlo en un servicio remoto.

    Paso 21. Crear una cuenta en GitHub

    Entra en GitHub y crea una cuenta si no tienes una.

    Después, crea un nuevo repositorio desde el botón de creación de repositorios.

    Configúralo con estos datos:

    CampoValor
    Repository nameministerio-promesas
    DescriptionPrograma electoral ficticio de Gitlandia
    VisibilidadPúblico, o privado si así lo indica el profesor
    Add READMEDesactivado
    Add .gitignoreDesactivado
    Choose a licenseNinguna por ahora

    Es importante no inicializar el repositorio remoto con archivos, porque ya tenemos un proyecto local con su propio historial. GitHub Docs

    Paso 22. Vincular Git local con GitHub

    Copia la dirección HTTPS del repositorio que acabas de crear.

    Será similar a:

    https://github.com/TU_USUARIO/ministerio-promesas.git

    Vuelve a la terminal, dentro de ministerio-promesas.

    Ejecuta:

    git remote add origin https://github.com/TU_USUARIO/ministerio-promesas.git

    Sustituye TU_USUARIO por tu nombre de usuario de GitHub.

    Consulta los remotos:

    git remote -v

    Verás una dirección de envío (push) y otra de descarga (fetch).

    origin es simplemente el nombre que hemos asignado al repositorio remoto. No es una palabra reservada que tenga que utilizarse obligatoriamente.

    Paso 23. Publicar el primer repositorio

    Ejecuta:

    git push -u origin main

    La opción -u establece la relación de seguimiento entre nuestra rama local main y la rama remota correspondiente.

    A partir de ese momento, los siguientes envíos podrán hacerse simplemente mediante:

    git push

    Importante: autenticación

    GitHub no admite utilizar la contraseña normal de tu cuenta como contraseña de Git para operaciones HTTPS. Tendrás que usar un método de autenticación compatible, como Git Credential Manager, GitHub CLI o un token de acceso personal con los permisos adecuados.

    Una opción especialmente cómoda para un entorno de prácticas es utilizar GitHub CLI:

    gh auth login

    Este comando requiere tener gh instalado. En el asistente selecciona GitHub.com, HTTPS y sigue las instrucciones de autenticación.

    Nunca escribas tokens ni contraseñas reales dentro de los archivos de la práctica.

    Paso 24. Comprobar la publicación

    Vuelve al navegador, abre tu repositorio de GitHub y actualiza la página.

    Deberían aparecer programa.md, oposicion.md, los directorios públicos, .gitignore y el historial.

    Comprueba especialmente que secretos/claves.txt no se ha publicado.

    Paso 25. Crear un README para los visitantes

    Un repositorio debería explicar qué contiene y cómo utilizarlo.

    Crea:

    nano README.md

    Añade:

    # Ministerio de las Promesas Imposibles
    
    Bienvenido al repositorio oficial del Gobierno
    de Gitlandia.
    
    ## Objetivo
    
    Aprender Git mediante un programa electoral
    ficticio que cambia constantemente.
    
    ## Archivos
    
    - programa.md: Programa electoral oficial.
    - oposicion.md: Propuestas de la oposición.
    - economia/: Presupuestos.
    - comunicacion/: Comunicados oficiales.
    
    ## Tecnología
    
    - Linux
    - Git
    - GitHub
    - Markdown
    
    ## Advertencia
    
    Todos los personajes y propuestas son ficticios.
    
    Proyecto educativo individual.

    Registra y publica los cambios:

    git add README.md
    
    git commit -m "Documentación oficial del repositorio"
    
    git push

    Actualiza la página de GitHub.

    El contenido del README debería mostrarse automáticamente en la página del proyecto.

    Fase 10. Sincronización y clonación

    Paso 26. Simular una modificación desde otro ordenador

    Queremos comprobar qué sucede cuando el repositorio remoto tiene cambios que aún no existen en nuestra máquina virtual.

    Abre el archivo README.md directamente en GitHub y utiliza su opción de edición.

    Añade al final:

    ## Comunicado de última hora
    
    El ministro anuncia que se estudiará
    la posibilidad de cumplir alguna promesa.

    Guarda la modificación mediante un commit desde GitHub.

    Acabamos de crear una versión nueva que existe en GitHub, pero todavía no en nuestra máquina virtual.

    Paso 27. Descargar los cambios

    Vuelve a la terminal de Ubuntu.

    Ejecuta:

    git fetch origin

    Este comando descarga información y objetos del repositorio remoto, pero no integra automáticamente los cambios en tu rama local.

    Comprueba las diferencias:

    git log --oneline HEAD..origin/main

    Después ejecuta:

    git pull --ff-only

    En este caso, como no hemos realizado nuevos commits locales después de la publicación, Git debería poder actualizar mediante fast-forward.

    Comprueba el README:

    cat README.md

    La modificación introducida desde GitHub debería estar disponible localmente.

    Pregunta: ¿Qué diferencia existe entre git fetch, git pull y git push?

    Paso 28. Clonar el proyecto en otro directorio

    Vamos a simular que hemos adquirido un nuevo ordenador o que necesitamos restaurar el proyecto después de perder la máquina virtual.

    Sal del directorio de trabajo:

    cd ~/proyectos-git

    Crea un directorio nuevo:

    mkdir ordenador-nuevo
    cd ordenador-nuevo

    Clona tu repositorio:

    git clone https://github.com/TU_USUARIO/ministerio-promesas.git

    Entra en él:

    cd ministerio-promesas

    Comprueba:

    git status
    git remote -v
    git log --oneline
    ls -la

    El repositorio clonado tendrá los archivos publicados y su historial Git.

    No contendrá los archivos locales ignorados que no se subieron a GitHub.

    Última misión

    Desde este nuevo clon, añade a README.md una sección titulada «El Ministerio sobrevive al cambio de ordenador».

    Después:

    git add README.md
    
    git commit -m "El Ministerio sobrevive al cambio de ordenador"
    
    git push

    Regresa al repositorio original:

    cd ~/proyectos-git/ministerio-promesas

    Y actualízalo:

    git pull --ff-only

    Comprueba que el cambio realizado en el nuevo clon aparece también en el original.

    Hemos trabajado sobre el mismo proyecto desde dos directorios diferentes, sin necesitar un trabajo colaborativo entre personas.

    Fase 11. El examen del ministro

    En esta última fase, los alumnos realizarán pequeñas operaciones sin copiar exactamente la secuencia anterior. Deben identificar los comandos necesarios y justificar su elección.

    Misiones finales

    Marca las completadas

    0 de 7 misiones

    0%Crear un archivo ministros.md con tres ministros ficticios y registrar un commit.Añadir una cuarta promesa al programa electoral, identificar el cambio con git diff y registrarlo.Modificar accidentalmente economia/presupuesto.txt y recuperar la versión confirmada.Crear un archivo temporal discurso.tmp y comprobar que Git lo ignora.Crear una rama llamada reforma, añadir una propuesta, registrarla y fusionarla con main.Publicar todos los cambios en GitHub y comprobar que el repositorio local está sincronizado.Mostrar el historial completo con un gráfico de los commits.

    Comandos que deben dominar

    ComandoFunción
    git init -b mainInicializar repositorio
    git statusConsultar estado
    git add archivoPreparar cambios
    git commit -m "mensaje"Registrar versión
    git log --onelineConsultar historial
    git diffComparar cambios
    git show HEADInspeccionar último commit
    git restore archivoRecuperar contenido
    git restore --staged archivoRetirar del staging
    git revert HEADRevertir un commit
    git switch -c ramaCrear y cambiar de rama
    git merge ramaFusionar ramas
    git remote -vConsultar remotos
    git pushEnviar commits
    git fetchDescargar información remota
    git pullDescargar e integrar cambios
    git clone URLClonar repositorio

    Adaptación para Windows

    En Windows pueden instalar Git for Windows y utilizar Git Bash, que permite ejecutar prácticamente todos los comandos Linux de esta práctica.

    Para quienes utilicen PowerShell, las principales diferencias están en los comandos del sistema, no en Git.

    OperaciónBash (Linux y Git Bash)PowerShell
    Directorio actualpwdpwd
    Listar archivosls -laGet-ChildItem -Force
    Crear carpetamkdir proyectomkdir proyecto
    Mostrar archivocat archivo.txtGet-Content archivo.txt
    Eliminar archivorm archivo.txtRemove-Item archivo.txt
    Editar archivonano archivo.txtnotepad archivo.txt
    Consultar Gitgit statusgit status

    Para mantener la práctica sencilla, recomiendo que todos trabajen con la terminal Linux de su máquina virtual, usando Windows solamente como demostración adicional.

    Entrega de la práctica

    Cada alumno deberá entregar un archivo README.md o informe.md con las respuestas a las preguntas, las explicaciones de los incidentes y las capturas necesarias.

    Además, deberá facilitar el enlace de su repositorio en GitHub y demostrar que contiene el historial de commits.

  • Módulo 1. Introducción a la documentación técnica

    Módulo 1. Introducción a la documentación técnica

    En este primer módulo vamos a sentar las bases del curso. Antes de aprender a hacer README, manuales, esquemas o documentación profesional, es importante entender qué es realmente la documentación técnica, por qué es tan importante y por qué en tantos proyectos termina siendo un desastre o directamente no existe.

    La idea de esta unidad es que el alumno comprenda que documentar no es “rellenar papel”, sino una parte fundamental del trabajo técnico. Un proyecto mal documentado puede convertirse en un problema incluso aunque técnicamente esté bien hecho.

    En este módulo se trabajará:

    • qué es la documentación técnica
    • por qué suele fallar la documentación en proyectos reales
    • diferencias entre documentar para uno mismo, para un equipo y para un cliente
    • tipos de documentación en informática

    ¿Qué es la documentación técnica?

    La documentación técnica es el conjunto de textos, esquemas, instrucciones, referencias y evidencias que explican cómo funciona un sistema, cómo se instala, cómo se usa, cómo se mantiene o cómo se ha construido.

    Dicho de forma sencilla:
    la documentación técnica sirve para que una persona pueda entender, usar, mantener, revisar o continuar un trabajo técnico sin depender totalmente de quien lo creó.

    Ejemplos de documentación técnica

    En informática, documentación técnica puede ser por ejemplo:

    • un README de un proyecto en GitHub
    • un manual de instalación de un servidor
    • una guía de despliegue de una aplicación
    • un documento con la arquitectura de una red
    • un procedimiento para hacer copias de seguridad
    • una memoria técnica de un proyecto
    • un informe de auditoría o de incidencia
    • una wiki interna con procesos y configuraciones

    ¿Por qué es tan importante documentar?

    Porque en el mundo real los proyectos no viven solo el día que se crean.

    Un proyecto técnico normalmente pasa por varias fases:

    • se diseña
    • se implementa
    • se prueba
    • se entrega
    • se mantiene
    • se modifica
    • se corrige
    • se reutiliza o amplía

    Si no existe documentación, todo depende de la memoria de una persona.
    Y eso provoca errores, pérdida de tiempo, dependencia del autor original y muchos problemas cuando hay que revisar o retomar el trabajo.

    Una idea clave

    Un proyecto sin documentación puede funcionar hoy, pero convertirse en un problema mañana.


    ¿Qué suele pasar en los proyectos reales?

    En muchísimos proyectos la documentación falla por motivos muy parecidos.

    Problemas habituales

    • no se documenta desde el principio
    • se deja “para el final”
    • se escribe deprisa y sin estructura
    • se da por hecho que cosas importantes “ya se entienden”
    • se documenta pensando solo en quien lo ha hecho
    • la documentación se queda desactualizada
    • no se distingue entre tipos de documento
    • se mezcla información técnica, organizativa y personal sin orden
    • no se incluyen evidencias, validaciones ni contexto

    Resultado de todo esto

    Al final aparecen documentos que:

    • no sirven para instalar nada
    • no explican bien el proyecto
    • no ayudan a otra persona
    • no permiten reproducir el trabajo
    • quedan abandonados
    • generan confusión en lugar de ayudar

    Documentar no es escribir mucho

    Uno de los errores más frecuentes es pensar que “más texto” significa “mejor documentación”.

    No siempre es así.

    Una buena documentación no tiene por qué ser enorme.
    Tiene que ser:

    • clara
    • ordenada
    • útil
    • precisa
    • fácil de consultar
    • pensada para quien la va a leer

    Hay documentación breve que funciona muy bien, y documentación larguísima que no sirve para nada.


    ¿Para quién se documenta?

    Esta es una de las preguntas más importantes del módulo.

    No se documenta igual para todos los destinatarios.
    La forma de documentar cambia mucho según quién va a leer el documento.


    Documentar para uno mismo

    Cuando una persona documenta para sí misma, normalmente busca:

    • recordar pasos
    • guardar comandos
    • anotar configuraciones
    • dejar registro de errores y soluciones
    • construir una base de conocimiento personal

    Características habituales

    • más libertad en el formato
    • lenguaje más directo
    • menos contexto general
    • más valor práctico inmediato
    • organización pensada para el propio autor

    Ejemplo

    Una nota en Obsidian con comandos para configurar Apache y MySQL en Ubuntu.


    Documentar para un equipo

    Cuando se documenta para un equipo, la documentación debe ser más clara, más ordenada y más estandarizada.

    Aquí ya no basta con que “yo lo entienda”.
    Tiene que entenderlo otra persona que quizá no estuvo presente durante el proceso.

    Características habituales

    • lenguaje más claro y neutral
    • estructura estable
    • pasos reproducibles
    • mayor precisión
    • contexto suficiente
    • convenciones compartidas
    • mantenimiento continuo

    Ejemplo

    Una guía interna para desplegar una aplicación web en un servidor de pruebas.


    Documentar para un cliente o para una entrega formal

    Aquí la documentación debe tener además una presentación más cuidada y una explicación más completa del contexto, objetivos y resultados.

    Características habituales

    • tono más profesional
    • mejor presentación visual
    • organización muy clara
    • explicación de objetivos, alcance y resultados
    • vocabulario comprensible para perfiles no tan técnicos
    • formato más formal: Word, PDF, memoria, informe, etc.

    Ejemplo

    La memoria técnica de un proyecto final, con portada, índice, imágenes, fases, decisiones técnicas y conclusiones.


    Comparativa rápida

    Tipo de documentaciónDestinatarioObjetivo principalEstilo habitual
    PersonalUno mismoRecordar y reutilizarDirecto y práctico
    De equipoCompañeros o técnicosCompartir conocimiento y mantener procesosClaro, estructurado y reproducible
    Formal o de clienteProfesorado, cliente, responsables, tribunalExplicar, justificar y entregarProfesional, completo y bien presentado

    Tipos de documentación en informática

    En informática no existe un solo tipo de documentación.
    Hay varias categorías, y cada una cumple una función diferente.

    Entender esto es muy importante porque muchos errores vienen de mezclarlo todo en un solo documento.


    1. Documentación de producto

    Es la documentación que explica un producto, una aplicación, un sistema o una herramienta concreta.

    Suele incluir

    • qué es
    • para qué sirve
    • cómo se instala
    • cómo se configura
    • cómo se usa
    • qué requisitos tiene
    • qué estructura interna presenta

    Ejemplos

    • README de una aplicación
    • manual de usuario técnico
    • documentación de API
    • guía de instalación de software

    2. Documentación de proceso

    Explica cómo se realiza una tarea o un conjunto de tareas.

    No se centra tanto en “qué es el producto”, sino en qué pasos hay que seguir para hacer algo correctamente.

    Suele incluir

    • objetivo del proceso
    • requisitos previos
    • secuencia de pasos
    • validación
    • problemas frecuentes
    • resultado esperado

    Ejemplos

    • procedimiento de despliegue
    • guía de copia de seguridad
    • proceso de alta de usuarios
    • checklist de hardening
    • guía de restauración de servicios

    3. Documentación operativa

    Es la documentación que sirve para operar, administrar o mantener sistemas en funcionamiento.

    Está muy relacionada con ASIR, sistemas, administración, redes y explotación técnica.

    Suele incluir

    • configuraciones
    • servicios
    • puertos
    • rutas
    • comandos
    • validaciones
    • acciones de mantenimiento
    • actuación ante fallos

    Ejemplos

    • runbook de administración
    • guía de reinicio de servicios
    • procedimientos de monitorización
    • documentación de una infraestructura de red
    • inventario técnico de máquinas o servicios

    4. Documentación de soporte

    Es la documentación pensada para resolver dudas, incidencias o problemas recurrentes.

    Suele incluir

    • preguntas frecuentes
    • errores comunes
    • pasos de comprobación
    • diagnósticos básicos
    • soluciones conocidas

    Ejemplos

    • FAQ técnica
    • base de conocimiento
    • guía de resolución de incidencias
    • documentación de errores frecuentes

    5. Documentación académica y de entrega

    Es muy habitual en entornos educativos, proyectos fin de ciclo, memorias, prácticas guiadas y entregas técnicas.

    Aquí no solo importa el funcionamiento, sino también explicar el proceso, justificar decisiones y demostrar el trabajo realizado.

    Suele incluir

    • introducción
    • objetivos
    • análisis
    • requisitos
    • diseño
    • implementación
    • capturas
    • pruebas
    • conclusiones
    • bibliografía o referencias

    Ejemplos

    • memoria de TFG o TFM
    • entrega de una práctica técnica
    • informe de laboratorio
    • documentación de un proyecto de clase

    6. Documentación viva vs. documentación abandonada

    Este punto es especialmente importante.

    Documentación viva

    Es la que se mantiene actualizada y sigue siendo útil con el paso del tiempo.

    Características

    • se revisa
    • se corrige
    • se adapta a cambios
    • refleja el estado real del proyecto
    • acompaña al trabajo técnico

    Documentación abandonada

    Es la que se escribió una vez y nunca más se revisó.

    Problemas típicos

    • comandos que ya no sirven
    • capturas antiguas
    • rutas que han cambiado
    • versiones desactualizadas
    • información incompleta o engañosa

    Idea importante

    Una documentación antigua puede ser peor que no tener documentación, porque da una falsa sensación de confianza.


    Ejemplo sencillo para entenderlo

    Imagina una práctica donde un alumno monta un servidor web con Apache, PHP y MySQL.

    Si documenta bien:

    • explica requisitos
    • indica comandos
    • organiza pasos
    • muestra validaciones
    • añade errores encontrados
    • incluye estructura del proyecto
    • deja claro cómo reproducirlo

    Si documenta mal:

    • pone cuatro comandos sueltos
    • no indica orden
    • no explica qué instaló realmente
    • no muestra resultado
    • no aclara versiones ni rutas
    • no se entiende qué hizo ni cómo repetirlo

    Técnicamente puede haber hecho lo mismo, pero el valor del trabajo cambia muchísimo.


    Errores muy frecuentes al empezar a documentar

    Estos errores conviene enseñarlos desde el principio:

    • escribir pensando “ya me acordaré”
    • no poner títulos claros
    • mezclar teoría y práctica sin orden
    • usar frases ambiguas
    • copiar comandos sin explicar para qué sirven
    • no validar resultados
    • no anotar problemas reales
    • no diferenciar entre borrador y versión final
    • documentar solo el resultado y no el proceso




    Ejemplos

    CasoTipo de documentaciónDestinatarioObservación
    README de instalaciónDocumentación de productoUsuario técnico o desarrolladorExplica qué es y cómo usarlo
    Documento en Word con memoriaDocumentación académica y de entregaProfesorado, cliente o tribunalPresentación formal
    Nota de Obsidian con comandosDocumentación personal u operativaUno mismoUso interno y práctico
    Guía de despliegue en ApacheDocumentación de proceso u operativaEquipo técnicoProcedimiento reproducible
    Lista de errores frecuentesDocumentación de soporteUsuarios o técnicosAyuda a resolver incidencias
    Documento obsoletoDocumentación abandonadaPuede confundir a cualquieraNo refleja la realidad actual

    Ideas clave para recordar

    Documentar no es decorar un proyecto: es hacerlo comprensible y mantenible.

    Una buena documentación ayuda a repetir, mantener, explicar y mejorar un trabajo técnico.

    No toda la documentación sirve para lo mismo: hay que elegir bien el tipo de documento.

    La documentación útil está pensada para quien la va a leer.

    Una documentación sin mantenimiento termina perdiendo valor.


    Caso de uso: despliegue de una aplicación web interna para gestión de incidencias

    Una pequeña empresa llamada NetSecure Solutions necesita una aplicación web interna para que el equipo técnico pueda registrar incidencias informáticas, asignarlas a distintos técnicos y hacer seguimiento de su resolución.

    Un desarrollador del equipo ha creado una primera versión de la aplicación usando:

    • PHP
    • MySQL
    • Apache
    • JavaScript
    • HTML y CSS

    La aplicación funciona, pero ahora surge un problema habitual en muchos proyectos técnicos:

    • el sistema debe instalarse también en otro servidor
    • otros técnicos tienen que poder mantenerlo
    • un responsable debe entender qué incluye el proyecto
    • si aparece un error, alguien debe saber cómo revisarlo
    • si el desarrollador original no está, el trabajo debe poder continuar

    Para evitar depender únicamente de la memoria del autor, el equipo decide crear una documentación técnica completa del proyecto.

    ¿Qué documentación necesitarían?

    En este caso podrían necesitar, por ejemplo:

    • un README principal para explicar el proyecto
    • una guía de instalación para desplegarlo en otro equipo
    • una guía de configuración de la base de datos
    • una documentación de estructura del proyecto
    • una guía operativa para revisar logs y reiniciar servicios
    • una base de incidencias frecuentes
    • una memoria técnica para presentar el proyecto a dirección o a un cliente

    ¿Por qué este caso de uso es bueno para el módulo?

    Porque permite ver claramente que:

    • no toda la documentación sirve para lo mismo
    • un único documento no siempre es suficiente
    • el destinatario cambia según el documento
    • un proyecto técnico necesita más de un tipo de documentación

    Ejemplo de índice

    A continuación tienes un índice de ejemplo para la documentación de este proyecto ficticio. Te puede servir para enseñar a los alumnos cómo se organiza un documento técnico amplio.

    Índice de ejemplo: Documentación técnica del proyecto “NetSecure Tickets”

    1. Introducción

    1.1. Descripción general del proyecto
    1.2. Objetivo de la aplicación
    1.3. Alcance del sistema
    1.4. Público al que va dirigida esta documentación

    2. Visión general del proyecto

    2.1. Problema que resuelve
    2.2. Funcionalidades principales
    2.3. Tecnologías utilizadas
    2.4. Estructura general de funcionamiento

    3. Requisitos previos

    3.1. Requisitos de hardware
    3.2. Requisitos de software
    3.3. Versiones recomendadas
    3.4. Dependencias necesarias

    4. Instalación del entorno

    4.1. Instalación de Apache
    4.2. Instalación de PHP
    4.3. Instalación de MySQL
    4.4. Configuración inicial del servidor
    4.5. Verificación del entorno

    5. Despliegue de la aplicación

    5.1. Copia de archivos del proyecto
    5.2. Estructura de carpetas
    5.3. Configuración de conexión a base de datos
    5.4. Importación de la base de datos
    5.5. Prueba inicial de funcionamiento

    6. Uso básico de la aplicación

    6.1. Pantalla principal
    6.2. Registro de incidencias
    6.3. Consulta de incidencias
    6.4. Asignación a técnicos
    6.5. Cierre de incidencias

    7. Estructura técnica del proyecto

    7.1. Organización de archivos
    7.2. Archivos principales
    7.3. Relación entre frontend y backend
    7.4. Base de datos y tablas utilizadas

    8. Procedimientos operativos

    8.1. Reinicio de servicios
    8.2. Revisión de logs
    8.3. Copia de seguridad de la base de datos
    8.4. Restauración básica
    8.5. Comprobaciones de estado

    9. Incidencias frecuentes

    9.1. Error de conexión a MySQL
    9.2. Error 403 o 404 en Apache
    9.3. Problemas con permisos de archivos
    9.4. Fallos al cargar estilos o scripts
    9.5. Errores comunes y solución

    10. Mejoras futuras

    10.1. Autenticación de usuarios
    10.2. Panel de administración
    10.3. Exportación de incidencias
    10.4. Sistema de avisos por correo

    11. Conclusiones

    11.1. Resultado obtenido
    11.2. Valor del sistema
    11.3. Posibles ampliaciones

    12. Anexos

    12.1. Capturas de pantalla
    12.2. Comandos utilizados
    12.3. Script SQL inicial
    12.4. Referencias técnicas


    Versión más corta de índice para un README

    Si quieres enseñar también la diferencia entre un documento amplio y un README más simple, podrías poner este otro ejemplo:

    Índice de ejemplo de README

    1. Nombre del proyecto
    2. Descripción
    3. Objetivo
    4. Tecnologías utilizadas
    5. Requisitos previos
    6. Instalación
    7. Configuración
    8. Ejecución
    9. Estructura del proyecto
    10. Problemas frecuentes
    11. Mejoras futuras
    12. Autor

  • Módulo 2. Principios de una buena documentación técnica

    Módulo 2. Principios de una buena documentación técnica

    En el módulo anterior vimos qué es la documentación técnica, por qué es importante y qué tipos de documentación existen en informática.
    Ahora toca dar un paso más: entender qué hace que una documentación sea realmente buena.

    Porque no basta con documentar.
    También hay que documentar bien.

    En este módulo el alumno aprenderá cuáles son los principios que convierten un documento técnico en algo útil, claro y profesional. También verá errores muy frecuentes al redactar documentación y aprenderá a detectarlos y corregirlos.

    En esta unidad se trabajará:

    • claridad
    • precisión
    • estructura
    • consistencia
    • legibilidad
    • errores comunes al redactar documentos técnicos

    ¿Qué significa documentar bien?

    Documentar bien significa crear un documento que otra persona pueda leer y usar sin perder tiempo, sin interpretar cosas ambiguas y sin tener que preguntarle constantemente al autor.

    Una buena documentación técnica debe ayudar a responder preguntas como estas:

    • ¿qué es esto?
    • ¿para qué sirve?
    • ¿cómo se instala?
    • ¿cómo se usa?
    • ¿qué pasos hay que seguir?
    • ¿qué requisitos tiene?
    • ¿cómo sé si funciona?
    • ¿qué hago si falla?

    Si el documento no ayuda a responder este tipo de preguntas, entonces probablemente está incompleto o mal planteado.


    Idea clave del módulo

    Una documentación técnica no se valora por lo mucho que ocupa, sino por lo útil que resulta.


    1. Claridad

    La claridad es uno de los pilares más importantes de cualquier documentación técnica.

    Un documento claro permite que el lector entienda rápido lo que se le está explicando.
    No obliga a releer varias veces una frase ni a deducir lo que el autor quería decir.

    Una documentación clara:

    • usa frases directas
    • evita rodeos innecesarios
    • explica cada paso de forma comprensible
    • separa bien las ideas
    • no mezcla demasiadas cosas en el mismo apartado

    Ejemplo poco claro

    Aquí habría que configurar el servidor para que funcione correctamente según lo que se necesite.

    Ejemplo más claro

    Edita el archivo de configuración de Apache y cambia el puerto de escucha a 8080. Después reinicia el servicio con systemctl restart apache2.

    En el segundo caso, el lector sabe exactamente qué hacer.


    2. Precisión

    La claridad no basta si el documento no es preciso.

    La precisión consiste en explicar las cosas de forma concreta, exacta y verificable.

    Una documentación precisa:

    • indica rutas reales
    • usa nombres correctos
    • menciona versiones cuando importa
    • diferencia comandos parecidos
    • evita expresiones vagas como “lo normal”, “más o menos”, “si hace falta”, “como siempre”

    Ejemplo impreciso

    Instala la base de datos y configura el usuario.

    Ejemplo preciso

    Instala MySQL Server, crea la base de datos inventario, y después crea el usuario appuser con permisos sobre esa base de datos.

    La segunda versión reduce dudas y mejora la reproducibilidad.


    3. Estructura

    Muchas veces un documento falla no porque su contenido sea malo, sino porque está mal organizado.

    Un texto técnico necesita una estructura lógica.
    El lector debe saber dónde empieza una idea, dónde están los pasos, dónde están los requisitos y dónde están los problemas frecuentes.

    Una buena estructura suele separar:

    • introducción o contexto
    • objetivo
    • requisitos previos
    • pasos a realizar
    • validación
    • errores frecuentes
    • conclusiones o siguientes pasos

    Problema muy común

    Hay documentación donde se mezclan:

    • teoría
    • comandos
    • capturas
    • opiniones
    • errores
    • resultados

    …todo ello sin ningún orden.

    Eso hace que el lector tenga que “buscar” la información en lugar de encontrarla de forma natural.


    Ejemplo de estructura básica útil

    1. Objetivo

    Qué se va a hacer.

    2. Requisitos previos

    Qué hace falta antes de empezar.

    3. Procedimiento

    Pasos ordenados.

    4. Validación

    Cómo comprobar que ha salido bien.

    5. Problemas frecuentes

    Qué errores pueden aparecer.

    6. Resultado final

    Qué se ha conseguido.


    4. Consistencia

    La consistencia significa mantener el mismo criterio a lo largo de todo el documento.

    Por ejemplo:

    • usar siempre los mismos nombres para las mismas cosas
    • no cambiar de estilo en cada apartado
    • seguir la misma lógica en títulos y subtítulos
    • mantener el mismo formato para comandos, rutas, tablas y notas

    Ejemplo de falta de consistencia

    En una parte del documento escribes:

    • Base de datos
    • Usuario administrador
    • Carpeta del proyecto

    Y más adelante escribes:

    • BD
    • admin
    • directorio principal

    Aunque no parezca grave, este tipo de cambios genera confusión.

    También afecta al formato

    Por ejemplo, no conviene que en una parte los comandos estén así:

    sudo apt update

    y más adelante aparezcan mezclados dentro del texto sin destacar, o que unas rutas lleven formato y otras no.

    La consistencia da sensación de orden y profesionalidad.


    5. Legibilidad

    La legibilidad tiene que ver con lo fácil que resulta leer y recorrer el documento.

    No solo importa lo que se dice, sino cómo se presenta.

    Mejora la legibilidad:

    • usar títulos claros
    • crear apartados cortos
    • usar listas cuando conviene
    • separar bloques de código
    • dejar espacio entre secciones
    • usar tablas si ayudan a resumir
    • destacar notas importantes
    • no escribir párrafos gigantescos

    Ejemplo de mala legibilidad

    Un texto largo, sin subtítulos, con comandos mezclados dentro de frases muy extensas.

    Ejemplo de buena legibilidad

    Un documento con:

    • apartados definidos
    • comandos en bloques
    • pasos numerados
    • advertencias visibles
    • ejemplos separados del texto principal

    La legibilidad es especialmente importante en documentación técnica porque muchas veces no se lee de principio a fin: se consulta por partes.


    6. Orientación al lector

    Una documentación técnica no debe escribirse pensando solo en quien la redacta.
    Debe escribirse pensando en quien la va a usar.

    Eso significa que el documento debe adaptarse al perfil del lector.

    No es lo mismo escribir para:

    • uno mismo
    • un compañero técnico
    • un profesor
    • un cliente
    • un usuario final

    Ejemplo

    Si documentas una práctica para alumnos principiantes, probablemente debas incluir:

    • más contexto
    • pasos más detallados
    • explicaciones de comandos
    • ejemplos visuales

    Si documentas para un equipo técnico experto, quizá puedas ser más directo y conciso.


    7. Reproducibilidad

    Una de las mejores formas de medir la calidad de una documentación técnica es esta:

    ¿Otra persona podría repetir el proceso con ese documento?

    Si la respuesta es no, entonces la documentación no está cumpliendo bien su función.

    Para que un documento sea reproducible debe incluir:

    • requisitos previos
    • pasos en orden
    • comandos completos
    • rutas correctas
    • parámetros importantes
    • validación de resultado
    • contexto mínimo

    Ejemplo

    No basta con poner:

    Configura Apache para el proyecto.

    Eso no es reproducible.

    Es mejor algo como:

    1. Copia el proyecto a /var/www/html/app.
    2. Edita el archivo de virtual host.
    3. Define DocumentRoot /var/www/html/app.
    4. Activa el sitio.
    5. Reinicia Apache.
    6. Comprueba el acceso desde el navegador.

    8. Mantenibilidad

    Una buena documentación no debe servir solo hoy.
    También debe poder mantenerse con cierta facilidad.

    Una documentación mantenible:

    • está bien organizada
    • tiene secciones reutilizables
    • se puede actualizar sin rehacerla entera
    • separa lo estable de lo que cambia mucho
    • evita repeticiones innecesarias

    Ejemplo

    Si una versión del software cambia con frecuencia, conviene que la documentación tenga una sección concreta para versiones o requisitos, en lugar de repartir esa información por todo el documento.


    Errores comunes al redactar documentación técnica

    Ahora vamos a ver algunos de los errores más frecuentes. Esta parte suele ayudar mucho a los alumnos porque les permite reconocer fallos típicos que ellos mismos cometen al empezar.


    Error 1. Dar cosas por supuestas

    El autor sabe lo que ha hecho y cree que el lector también lo entenderá.

    Ejemplo

    Configuramos el servicio como siempre y continuamos con la instalación.

    Problema:
    ¿Como siempre según quién?
    Eso solo lo entiende quien lo escribió.


    Error 2. Escribir pasos incompletos

    A veces se omiten pasos porque parecen obvios.

    Ejemplo

    Importa la base de datos y ejecuta la aplicación.

    Pero quizá falta indicar:

    • qué archivo SQL usar
    • con qué usuario
    • sobre qué base de datos
    • en qué orden hacerlo

    Error 3. No validar resultados

    Muchos alumnos ponen comandos, pero no indican cómo comprobar que funcionó.

    Ejemplo

    Instala Apache.

    Bien, pero falta decir:

    • cómo comprobar que está activo
    • qué comando usar
    • qué respuesta esperar
    • qué debería verse en navegador

    Error 4. Mezclar demasiadas cosas en el mismo apartado

    Por ejemplo, juntar en una misma sección:

    • teoría
    • comandos
    • explicación de errores
    • decisiones de diseño
    • conclusiones

    Esto vuelve la documentación caótica.


    Error 5. Usar frases ambiguas

    Ejemplos típicos

    • “configura lo necesario”
    • “haz los cambios correspondientes”
    • “instala lo que falte”
    • “corrige los errores si aparecen”

    Este tipo de redacción parece técnica, pero en realidad aporta muy poca información útil.


    Error 6. No adaptar el nivel de detalle

    A veces la documentación es tan breve que no sirve.
    Otras veces tiene tanto detalle irrelevante que entorpece la lectura.

    Hay que encontrar el nivel adecuado según el público y el objetivo.


    Error 7. No diferenciar entre borrador y documentación final

    Una lista rápida de notas personales no es lo mismo que una guía lista para entregar o compartir.

    Es importante enseñar al alumno que documentar también implica revisar, ordenar y pulir.


    Cómo mejorar una mala documentación

    Una buena forma de enseñar este módulo es mostrar que mejorar documentación no siempre significa reescribir todo desde cero.

    Muchas veces basta con aplicar una revisión guiada.

    Preguntas de revisión útiles

    Antes de dar un documento por bueno, conviene revisar:

    • ¿se entiende el objetivo?
    • ¿queda claro para quién está escrito?
    • ¿los pasos están ordenados?
    • ¿faltan requisitos previos?
    • ¿hay validación?
    • ¿hay frases ambiguas?
    • ¿se usan siempre los mismos términos?
    • ¿se puede localizar rápido cada parte?
    • ¿otra persona podría repetir el proceso?

    Ejemplo práctico: de documentación deficiente a documentación útil

    Versión deficiente

    Instalamos el servidor, cambiamos unas cosas de configuración y luego metemos la base de datos. Después ya se puede probar el proyecto. Si da error habrá que revisar permisos o la conexión.

    Versión mejorada

    Instalación del entorno

    1. Instala Apache con el comando:
    sudo apt install apache2 -y
    1. Instala MySQL Server:
    sudo apt install mysql-server -y
    1. Crea la base de datos proyecto_web:
    CREATE DATABASE proyecto_web;
    1. Importa el archivo proyecto_web.sql en esa base de datos.
    2. Copia los archivos del proyecto a:
    /var/www/html/proyecto_web
    1. Comprueba en el navegador que la aplicación responde correctamente.

    Validación

    • Verifica que Apache esté activo con:
    systemctl status apache2
    • Comprueba que MySQL esté funcionando:
    systemctl status mysql

    Aquí ya vemos claridad, estructura, precisión y validación.


    Qué debe aprender el alumno en este módulo

    Al terminar esta unidad, el alumno debe ser capaz de:

    • identificar si una documentación es clara o confusa
    • detectar frases ambiguas o imprecisas
    • organizar mejor un documento técnico
    • aplicar criterios de consistencia y legibilidad
    • redactar pasos reproducibles
    • revisar una documentación para mejorarla antes de entregarla

    Resultado práctico del módulo

    El alumno analiza una documentación técnica sencilla, detecta sus fallos y la mejora aplicando principios de claridad, precisión, estructura, consistencia y legibilidad.


    Actividad propuesta para el módulo

    Actividad: detectar y corregir errores de documentación

    Lee este fragmento de documentación:

    Se instala el servidor web y luego se configura todo para que funcione con la aplicación. Después se mete la base de datos y se comprueba si va bien. Si falla, revisar lo necesario.

    Tareas del alumno

    1. Indica qué problemas tiene este texto.
    2. Señala al menos 5 aspectos que deberían mejorarse.
    3. Reescribe el fragmento para convertirlo en una documentación técnica más útil.

    Solución orientativa

    Problemas detectados

    • no indica qué servidor web se instala
    • no explica qué significa “configurar todo”
    • no especifica cómo se importa la base de datos
    • no incluye rutas ni comandos
    • no explica cómo comprobar que funciona
    • no concreta qué hacer si falla

    Reescritura mejorada

    Instalación y configuración básica

    1. Instala Apache:
    sudo apt install apache2 -y
    1. Copia la aplicación a la carpeta:
    /var/www/html/app_incidencias
    1. Crea la base de datos app_incidencias en MySQL.
    2. Importa el archivo app_incidencias.sql.
    3. Edita el archivo de configuración de la aplicación para introducir:
    • nombre de la base de datos
    • usuario
    • contraseña
    • host
    1. Abre el navegador y accede a la URL del proyecto para comprobar que carga correctamente.

    Validación

    • comprueba el estado de Apache
    • verifica la conexión con MySQL
    • revisa permisos de archivos si la aplicación no carga

    Caso de uso inventado para este módulo

    Imagina que un alumno ha montado una pequeña aplicación de gestión de tareas en PHP y MySQL.
    Quiere entregar la práctica, pero su documentación consiste solo en:

    • una lista de comandos sueltos
    • una captura de la web funcionando
    • una frase que dice “la instalación es sencilla”
    • una mención rápida a la base de datos

    Aunque la aplicación funcione, esa documentación no sería suficiente para:

    • repetir el despliegue
    • corregir errores
    • mantener el proyecto
    • evaluarlo correctamente
    • entregarlo de forma profesional

    El problema no es solo el contenido técnico, sino cómo está explicado.


    Ejemplo de índice para un documento bien estructurado

    Índice de ejemplo

    1. Introducción
    2. Objetivo del documento
    3. Requisitos previos
    4. Instalación del entorno
    5. Configuración de la base de datos
    6. Despliegue de la aplicación
    7. Validación del funcionamiento
    8. Problemas frecuentes
    9. Conclusión

    Este índice ya muestra una secuencia lógica y fácil de seguir.


    Ideas clave para recordar

    Una buena documentación debe ser clara, precisa y útil.

    Si un paso no se puede repetir, la documentación está incompleta.

    Escribir mucho no garantiza documentar bien.

    Una estructura ordenada facilita muchísimo el trabajo técnico.

    La revisión final forma parte de la documentación.

  • REDACTAR UNA MEMORIA TÉCNICA

    REDACTAR UNA MEMORIA TÉCNICA

    ¿Para qué sirve una memoria técnica?

    Una memoria técnica no es “un trabajo para entregar”.
    Es un documento que permite que otra persona pueda entender y reproducir exactamente lo que has hecho, sin preguntarte nada.

    En el entorno profesional, documentar es tan importante como configurar un servidor.

    Una memoria técnica es un documento estructurado que explica de forma clara, objetiva y detallada cómo se ha realizado un trabajo técnico.

    • No es un resumen.
    • No es una redacción larga.
    • No es una opinión.

    Es la descripción precisa de un proceso técnico para que otra persona pueda entenderlo, evaluarlo y, si quiere, reproducirlo.

    En ingeniería y en informática, la memoria técnica cumple una función muy concreta: convertir lo que has hecho en conocimiento transferible.

    Si configuras un servidor y no lo documentas, ese conocimiento vive solo en tu cabeza.
    Si lo documentas correctamente, se convierte en algo útil para un equipo, una empresa o incluso para ti mismo dentro de seis meses.

    Se usa principalmente para:

    – Documentar proyectos técnicos.
    – Justificar decisiones técnicas.
    – Permitir que otros reproduzcan una instalación o configuración.
    – Evaluar trabajos académicos o profesionales.
    – Dejar constancia formal de lo realizado.

    En el ámbito educativo, sirve además para entrenar una competencia clave: pensar de forma estructurada. Cuando redactas una memoria técnica estás organizando ideas, justificando pasos y demostrando que entiendes lo que haces.

    En el mundo profesional, la memoria técnica evita el caos. Imagina una empresa donde nadie documenta nada. Cada vez que algo falla, todo empieza desde cero. Eso no es ingeniería, es improvisación.

    Una buena memoria técnica tiene tres características fundamentales:

    • Precisión: explica exactamente lo que se ha hecho.
    • Claridad: cualquier técnico puede entenderla.
    • Reproducibilidad: permite repetir el proceso con el mismo resultado.

    En resumen, una memoria técnica transforma acciones en conocimiento estructurado. Y esa capacidad marca la diferencia entre “alguien que sabe hacer cosas” y “un profesional capaz de trabajar en equipo y mantener sistemas complejos”.

    Y aquí viene la idea interesante: escribir una memoria técnica no es solo comunicar. Es una forma de comprobar si realmente entiendes lo que has hecho. Porque si no puedes explicarlo con claridad, probablemente todavía no lo dominas del todo.

    Documentar es pensar. Y pensar bien es la base de cualquier disciplina técnica.


    ESTRUCTURA OBLIGATORIA DE LA MEMORIA


    1. Portada

    Debe incluir:

    • Título del proyecto o práctica
    • Módulo
    • Nombre del alumno
    • Fecha
    • Versión del documento (por ejemplo: 1.0)

    Ejemplo:

    Instalación y configuración de servidor Apache en Ubuntu Server


    2. Objetivo del proyecto

    En este apartado debes explicar:

    • Qué vas a realizar.
    • Qué problema estás resolviendo.
    • Qué resultado final se espera.

    Debe ser claro y técnico.

    ❌ Incorrecto:

    Vamos a instalar Apache.

    ✅ Correcto:

    Implementar y configurar un servidor Apache en Ubuntu Server para alojar un sitio web accesible desde la red local.


    3. Descripción del entorno

    Aquí debes indicar las condiciones técnicas en las que trabajas.

    3.1 Hardware

    • Equipo físico o máquina virtual.
    • Recursos asignados (RAM, CPU si es relevante).

    3.2 Sistema Operativo

    • Distribución.
    • Versión.
    • Arquitectura (si procede).

    3.3 Configuración de red

    • Dirección IP.
    • Tipo de red (NAT, Bridge, etc.).
    • Puertos utilizados.

    3.4 Software utilizado

    • Programas o servicios instalados.
    • Versiones si es posible.

    Este apartado es obligatorio porque permite reproducir el entorno.


    4. Desarrollo del proyecto

    Es la parte más importante del documento.

    Cada paso debe incluir:

    1. Qué se va a hacer.
    2. El comando o acción realizada.
    3. Una breve explicación técnica.
    4. El resultado obtenido.

    Ejemplo:


    4.1 Instalación de Apache

    Se instala el servidor web Apache utilizando el gestor de paquetes apt:

    sudo apt update
    sudo apt install apache2 -y

    Tras la instalación, el servicio se inicia automáticamente.
    Se comprueba su estado con el siguiente comando:

    sudo systemctl status apache2

    Resultado: El servicio aparece activo y escuchando en el puerto 80.


    ⚠ No se deben incluir comandos sin explicación.
    ⚠ No se deben insertar capturas sin describir lo que muestran.


    5. Pruebas realizadas

    Aquí debes demostrar que el sistema funciona correctamente.

    Ejemplos de pruebas:

    • Acceso desde navegador.
    • Comprobación de puertos abiertos.
    • Pruebas con ping, curl, netstat, ss, etc.

    Debes indicar:

    • Qué prueba realizas.
    • Qué resultado esperas.
    • Qué resultado obtienes.

    Si no se demuestra el funcionamiento, la práctica no está completa.


    6. Problemas encontrados y soluciones

    En este apartado debes explicar los errores o dificultades que han surgido.

    Formato recomendado:

    ProblemaCausaSolución

    Ejemplo:

    | Error 403 Forbidden | Permisos incorrectos en carpeta web | Se modificaron permisos con chmod |

    Este apartado es obligatorio.
    Si no has tenido problemas, debes indicarlo explícitamente.


    7. Conclusión técnica

    Debe ser breve y profesional.

    No se admiten opiniones personales.

    ❌ Incorrecto:

    Me ha parecido una práctica interesante.

    ✅ Correcto:

    Se ha configurado correctamente el servidor Apache, verificando su funcionamiento desde un equipo cliente de la red local.


    8. Anexos (si procede)

    Aquí puedes incluir:

    • Archivos completos de configuración.
    • Scripts utilizados.
    • Diagramas.
    • Información adicional relevante.

    Normas de redacción obligatorias

    • Utilizar lenguaje técnico y objetivo.
    • No escribir en primera persona.
    • No usar colores innecesarios.
    • Numerar correctamente los apartados.
    • Las capturas deben estar recortadas y ser legibles.
    • El código debe tener formato adecuado.
    • No copiar texto sin entenderlo.

    Errores frecuentes que debes evitar

    • Pegar comandos sin explicación.
    • Incluir capturas enormes sin describirlas.
    • No indicar el entorno utilizado.
    • Escribir conclusiones personales.
    • Entregar documentos sin estructura clara.

    Importante

    Documentar correctamente es una competencia técnica fundamental.

    Diferencia entre una Memoria Técnica y un README

    En el ámbito técnico es habitual encontrarse con ambos documentos: la memoria técnica y el archivo README. Aunque pueden parecer similares, no cumplen la misma función ni tienen el mismo nivel de profundidad.

    Comprender esta diferencia es importante para saber cuándo utilizar cada uno.

    ¿Qué es un README?

    Un README es un archivo introductorio que acompaña a un proyecto, normalmente en un repositorio (por ejemplo, en GitHub).

    Su función es explicar de forma clara y rápida:

    • Qué es el proyecto
    • Para qué sirve
    • Cómo instalarlo
    • Cómo usarlo
    • Qué requisitos necesita

    Un README no describe todo el proceso interno del proyecto. No detalla cada paso realizado. Su objetivo es orientar al usuario o desarrollador que quiera utilizar el proyecto.

    Es más breve, más práctico y más directo.

    Si la memoria técnica explica cómo se construyó el sistema, el README explica cómo usarlo.

    Diferencias principales

    La diferencia clave está en el nivel de profundidad y en el objetivo.

    La memoria técnica documenta el proceso completo.
    El README facilita el uso del resultado.

    Podemos resumirlo así:

    La memoria técnica responde a la pregunta:
    ¿Cómo se ha desarrollado este proyecto?

    El README responde a la pregunta:
    ¿Cómo puedo utilizar este proyecto?


    Ejemplo práctico

    Imaginemos que se instala y configura un servidor web Apache.

    La memoria técnica incluiría:

    • Descripción del entorno
    • Instalación paso a paso
    • Explicación de cada configuración
    • Problemas encontrados
    • Pruebas realizadas
    • Conclusión técnica

    El README incluiría:

    • Descripción del servidor
    • Requisitos mínimos
    • Pasos rápidos para instalarlo
    • Comandos necesarios
    • Cómo acceder al servicio

    La memoria explica el proceso completo.
    El README facilita la puesta en marcha.

  • Obsidian para documentar proyectos en Markdown

    Obsidian para documentar proyectos en Markdown

    1. Introducción

    En este tema aprenderás a utilizar Obsidian para crear y organizar documentación en formato Markdown. Los documentos se guardarán en una carpeta local y, posteriormente, podrán incorporarse a un repositorio de GitHub.

    El objetivo no es utilizar Obsidian como una nube ni como sustituto de GitHub. Obsidian será el editor de documentación y GitHub será el lugar donde se almacenen y entreguen los proyectos.

    2. ¿Qué es Obsidian?

    Obsidian es una aplicación para escribir y organizar notas mediante archivos Markdown. Cada nota es un archivo de texto con extensión .md y puede abrirse también con Visual Studio Code, cualquier editor de texto o directamente desde GitHub.

    Una de sus características principales es que los archivos se guardan en una carpeta normal del ordenador. Obsidian denomina bóveda o vault a esa carpeta.

    Con Obsidian podemos:

    • Crear archivos Markdown sin memorizar inicialmente toda la sintaxis.
    • Organizar documentos mediante carpetas.
    • Insertar imágenes, enlaces, listas, tablas y bloques de código.
    • Relacionar documentos entre sí.
    • Ver el resultado mientras escribimos.
    • Buscar rápidamente en toda la documentación.
    • Mantener una colección de apuntes o proyectos en archivos locales.

    Importante: una bóveda no es un formato especial ni un archivo comprimido. Es una carpeta normal que contiene documentos y recursos.

    3. Obsidian, Git y GitHub no son lo mismo

    HerramientaFunción
    ObsidianCrear, editar y organizar los documentos Markdown.
    GitRegistrar el historial de cambios del proyecto.
    GitHubAlojar el repositorio y permitir su entrega o revisión.

    El flujo de trabajo que utilizaremos será:

    Escribir en Obsidian → Guardar en la carpeta local → Confirmar con Git → Subir a GitHub

    4. Descargar Obsidian

    La descarga debe realizarse desde la página oficial:

    Descargar Obsidian

    Obsidian está disponible para Windows, macOS, Linux, Android, iPhone y iPad. En este curso utilizaremos principalmente la versión de escritorio.

    5. Instalación en Windows

    1. Accede a la página oficial de descarga.
    2. Localiza el apartado Windows.
    3. Pulsa Universal.
    4. Espera a que termine la descarga.
    5. Abre el archivo de instalación descargado.
    6. Sigue los pasos mostrados por el instalador.
    7. Abre Obsidian desde el menú Inicio.

    Si Windows muestra una advertencia, comprueba que el instalador procede del dominio oficial obsidian.md.

    6. Instalación en macOS

    1. Accede a la página oficial de descarga.
    2. Localiza el apartado Mac.
    3. Pulsa Universal.
    4. Abre el archivo descargado.
    5. Arrastra el icono de Obsidian hasta la carpeta Aplicaciones.
    6. Abre la carpeta Aplicaciones y ejecuta Obsidian.

    La primera vez, macOS puede pedir confirmación para abrir una aplicación descargada de Internet.

    7. Instalación en Linux

    La web oficial ofrece diferentes formatos: AppImage, Snap y paquete DEB. También aparece una versión Flatpak mantenida por la comunidad.

    Opción A: paquete DEB

    Esta opción resulta adecuada para Ubuntu, Debian y distribuciones derivadas.

    1. Descarga el paquete Deb desde la web oficial.
    2. Abre una terminal en la carpeta de descargas.
    3. Ejecuta:
    sudo apt install ./obsidian_*.deb
    1. Abre Obsidian desde el menú de aplicaciones.

    Opción B: AppImage

    1. Descarga el archivo AppImage.
    2. Abre una terminal en la carpeta donde se encuentre.
    3. Concede permiso de ejecución:
    chmod u+x Obsidian-*.AppImage
    1. Ejecuta la aplicación:
    ./Obsidian-*.AppImage

    Opción C: Flatpak

    Si el sistema ya tiene Flatpak y Flathub configurados:

    flatpak install flathub md.obsidian.Obsidian

    Para abrirlo desde la terminal:

    flatpak run md.obsidian.Obsidian

    8. Crear una bóveda local

    Al abrir Obsidian por primera vez aparecerá la pantalla de gestión de bóvedas.

    1. Pulsa Create junto a Create new vault.
    2. En Vault name, escribe:
    Documentacion-ASIR
    1. Pulsa Browse.
    2. Selecciona una ubicación fácil de encontrar, por ejemplo Documentos.
    3. Pulsa Create.

    Obsidian creará una carpeta llamada Documentacion-ASIR. Todos los documentos de la bóveda se guardarán físicamente dentro de ella.

    Una ubicación posible en Windows sería:

    C:\Users\alumno\Documents\Documentacion-ASIR

    En macOS o Linux podría ser:

    ~/Documentos/Documentacion-ASIR

    No crees la bóveda en una carpeta temporal, en Descargas ni dentro de otra bóveda.

    9. Crear la estructura inicial

    Dentro de la bóveda crea estas carpetas desde el explorador lateral de Obsidian:

    Documentacion-ASIR/
    ├── 00-Plantillas/
    ├── 01-Actividades/
    ├── 02-Proyectos/
    ├── 03-Apuntes/
    └── img/

    Su finalidad es:

    • 00-Plantillas: modelos reutilizables de documentos.
    • 01-Actividades: actividades breves realizadas durante el curso.
    • 02-Proyectos: proyectos de mayor tamaño.
    • 03-Apuntes: notas personales del alumno.
    • img: imágenes y capturas utilizadas en la documentación.

    10. Crear el primer README

    1. Selecciona la carpeta 01-Actividades.
    2. Crea una carpeta denominada actividad-01-markdown.
    3. Dentro de ella, crea una nota nueva.
    4. Cambia su nombre a README.

    Obsidian añadirá automáticamente la extensión y guardará el archivo como:

    README.md

    Escribe este contenido:

    # Actividad 1: introducción a Markdown
    
    ## Descripción
    
    Esta es mi primera documentación escrita con **Obsidian**.
    
    ## Objetivos
    
    - Aprender a crear un README.
    - Organizar una actividad.
    - Insertar imágenes.
    - Preparar el documento para GitHub.
    
    ## Conclusión
    
    En esta actividad he aprendido a crear y visualizar un documento Markdown.

    11. Modos de edición y lectura

    Obsidian permite trabajar principalmente con dos vistas:

    • Vista de edición: permite modificar el documento.
    • Vista de lectura: muestra el documento renderizado.

    También dispone de Live Preview, que presenta gran parte del formato mientras se escribe.

    Utiliza la vista de lectura antes de entregar una actividad para comprobar:

    • Que los títulos tienen la jerarquía correcta.
    • Que las listas aparecen correctamente.
    • Que las imágenes se muestran.
    • Que no existen enlaces rotos.
    • Que los bloques de código son legibles.

    12. Configuración recomendada para trabajar con GitHub

    Obsidian incorpora funciones propias que no siempre funcionan igual fuera de la aplicación. Para mantener la compatibilidad con GitHub, realiza esta configuración.

    12.1 Utilizar enlaces Markdown

    1. Abre Settings.
    2. Entra en Files and links.
    3. Desactiva Use [[Wikilinks]].

    Obsidian utilizará enlaces estándar:

    [Nombre del documento](otro-documento.md)

    En lugar de:

    [[otro-documento]]

    Los dos formatos funcionan en Obsidian, pero el primero ofrece mejor compatibilidad con otros editores y repositorios.

    12.2 Actualizar enlaces automáticamente

    En Settings → Files and links, mantén activada la actualización automática de enlaces internos. De esta manera, si renombras un documento desde Obsidian, sus referencias se actualizarán.

    12.3 Elegir dónde se guardan las imágenes

    1. Abre Settings.
    2. Entra en Files and links.
    3. Busca Default location for new attachments.
    4. Selecciona In subfolder under current folder.
    5. Escribe:
    img

    Así, cada actividad podrá conservar sus capturas junto al README:

    actividad-01-markdown/
    ├── README.md
    └── img/
        ├── paso-01.png
        └── resultado-final.png

    13. Insertar imágenes

    Puedes arrastrar una imagen desde el explorador de archivos hasta el documento. Obsidian la copiará a la ubicación configurada y la insertará en la nota.

    Para GitHub es recomendable que el resultado utilice esta sintaxis:

    ![Descripción de la captura](img/paso-01.png)

    Buenas prácticas:

    • Usa nombres descriptivos.
    • Evita espacios, tildes y caracteres especiales en los nombres.
    • Recorta las capturas para mostrar solo lo necesario.
    • Añade una explicación antes o después de cada captura.
    • No muestres contraseñas, tokens, datos personales ni direcciones privadas sensibles.
    • Comprueba la imagen tanto en Obsidian como en GitHub.

    14. Enlaces internos y externos

    Enlace a otro documento

    [Consultar instalación](instalacion.md)

    Enlace a una sección del mismo documento

    [Ir a las conclusiones](#conclusiones)

    Enlace externo

    [Documentación oficial de Obsidian](https://help.obsidian.md)

    Evita depender de enlaces especiales exclusivos de Obsidian si el documento debe visualizarse en GitHub.

    15. Bloques de código y comandos

    Para escribir un comando dentro de una frase utiliza una comilla invertida:

    Ejecuta el comando `git status`.

    Para escribir varios comandos utiliza un bloque e indica el lenguaje:

    ```bash
    git add .
    git commit -m "Completa la documentación"
    git push
    ```

    Ejemplo con Java:

    ```java
    public class Principal {
        public static void main(String[] args) {
            System.out.println("Hola");
        }
    }
    ```

    16. Diagramas Mermaid

    Obsidian puede representar diagramas Mermaid escritos dentro del propio documento.

    ```mermaid
    flowchart TD
        A[Crear documentación] --> B[Revisar en Obsidian]
        B --> C[Guardar cambios con Git]
        C --> D[Subir a GitHub]
    ```

    Antes de entregar, comprueba que el diagrama también se representa correctamente en GitHub.

    17. Plantilla básica para las actividades

    Guarda en 00-Plantillas un archivo llamado plantilla-actividad.md:

    # Título de la actividad
    
    ## Información
    
    - **Alumno:**
    - **Asignatura:**
    - **Fecha:**
    
    ## Descripción
    
    Explicación breve de la actividad.
    
    ## Objetivos
    
    - Objetivo 1.
    - Objetivo 2.
    
    ## Desarrollo
    
    ### Paso 1
    
    Explicación del paso.
    
    ![Descripción de la captura](img/paso-01.png)
    
    ## Problemas encontrados
    
    Describe los problemas y las soluciones aplicadas.
    
    ## Resultado
    
    Explica cómo has comprobado el funcionamiento.
    
    ## Conclusiones
    
    Resume lo aprendido con tus propias palabras.
    
    ## Referencias
    
    - [Documentación consultada](https://ejemplo.com)

    18. Llevar una actividad a GitHub

    La carpeta que se abra como repositorio debe contener directamente el proyecto y su documentación:

    mi-proyecto/
    ├── README.md
    ├── img/
    ├── src/
    └── otros-archivos-del-proyecto

    Puedes abrir esa misma carpeta como bóveda de Obsidian mediante Open folder as vault. Así editas el README directamente dentro del repositorio y evitas mantener dos copias diferentes.

    Cuando termines de documentar:

    git status
    git add README.md img/
    git commit -m "Añade la documentación de la actividad"
    git push

    Después, abre el repositorio en GitHub y comprueba visualmente el README.

    19. ¿Subir la configuración de Obsidian al repositorio?

    Obsidian crea una carpeta oculta denominada .obsidian con la configuración de la bóveda.

    Para actividades individuales normalmente no es necesario subirla. Puedes añadirla a .gitignore:

    .obsidian/

    Esto mantiene el repositorio centrado en la documentación y en los archivos del proyecto. Si un equipo necesita compartir una configuración concreta, deberá decidirlo expresamente.

    20. Plugins y temas

    Obsidian permite instalar temas y plugins, pero no son necesarios para crear buenos README.

    Durante las primeras actividades se recomienda:

    • Utilizar el tema predeterminado.
    • No instalar plugins comunitarios.
    • Aprender primero Markdown estándar.
    • Introducir nuevas funciones únicamente cuando resuelvan una necesidad real.

    Los plugins añaden complejidad y algunos generan contenido que no funciona correctamente fuera de Obsidian.

    21. Copias de seguridad y sincronización

    Que los archivos estén en el ordenador no significa que tengan una copia de seguridad.

    Recomendaciones:

    • Utiliza Git y GitHub para los proyectos del curso.
    • Realiza commits frecuentes y con mensajes descriptivos.
    • No confundas sincronización con copia de seguridad.
    • No guardes contraseñas ni secretos en la bóveda.
    • Comprueba qué archivos vas a subir mediante git status.

    Obsidian ofrece servicios opcionales de sincronización y publicación, pero no son necesarios para seguir este tema ni para entregar las actividades en GitHub.

    22. Consejos de organización

    • Utiliza un solo # para el título principal.
    • Organiza los apartados con ## y ###.
    • Mantén nombres coherentes: actividad-01, actividad-02, etc.
    • Evita nombres como final, final-bueno o final-definitivo-2.
    • Escribe primero la explicación y añade después la evidencia.
    • No conviertas el README en una colección de capturas.
    • Incluye siempre una sección de comprobación o resultado.
    • Explica los errores relevantes y cómo los resolviste.
    • Cita las fuentes consultadas.
    • Revisa el documento en GitHub antes de entregar.

    23. Errores frecuentes

    La imagen se ve en Obsidian, pero no en GitHub

    Comprueba que la imagen se encuentre dentro del repositorio y que la ruta respete exactamente mayúsculas y minúsculas:

    ![Resultado](img/resultado.png)

    El enlace funciona en Obsidian, pero no en GitHub

    Es posible que se haya utilizado un Wikilink. Sustitúyelo por un enlace Markdown estándar.

    El README aparece como texto sin formato

    Comprueba que se llama exactamente README.md y no README.md.txt.

    Hay demasiadas imágenes en la raíz

    Configura la ubicación de adjuntos y almacénalos en una carpeta img.

    Obsidian no muestra una bóveda anterior

    Selecciona Open folder as vault y elige la carpeta que contiene los archivos Markdown.

    24. Lista de comprobación antes de entregar

    • El archivo principal se llama README.md.
    • El README está dentro del repositorio correcto.
    • Las imágenes están dentro del repositorio.
    • Las rutas de las imágenes son relativas.
    • Los enlaces funcionan en GitHub.
    • Los títulos tienen una jerarquía lógica.
    • Los comandos están dentro de bloques de código.
    • No aparecen contraseñas, tokens ni datos sensibles.
    • La carpeta .obsidian está excluida si no es necesaria.
    • Se ha realizado un commit antes de la entrega.
    • Se ha comprobado la presentación final en GitHub.

    25. Actividad propuesta

    1. Instala Obsidian.
    2. Crea una bóveda local denominada Documentacion-ASIR.
    3. Crea la estructura de carpetas indicada en este manual.
    4. Configura los enlaces Markdown y la carpeta de imágenes.
    5. Crea un archivo README.md utilizando la plantilla básica.
    6. Inserta una captura en la carpeta img.
    7. Añade una lista, un enlace y un bloque de código.
    8. Revisa el documento en vista de lectura.
    9. Abre la carpeta con Visual Studio Code y comprueba que el archivo continúa siendo editable.
    10. Sube el resultado al repositorio indicado por el profesor.

    26. Referencias oficiales

  • Actividad: Mi primera guía en Markdown

    Actividad: Mi primera guía en Markdown

    1. Introducción

    En esta actividad aprenderás a crear un documento utilizando Markdown.

    Markdown permite elaborar documentación mediante archivos de texto con extensión .md. Se utiliza habitualmente para documentar proyectos informáticos en plataformas como GitHub y GitLab.

    En esta actividad no tendrás que instalar, programar ni configurar ningún servicio. El objetivo es únicamente aprender a crear documentación clara, ordenada y visual.

    2. Tarea que debes realizar

    Debes crear una guía titulada:

    Cómo organizar archivos y carpetas en un ordenador

    La guía explicará cómo crear y organizar una carpeta para una asignatura.

    La estructura que deberás explicar será parecida a esta:

    ASIR/
    ├── Implantación de Aplicaciones Web/
    │   ├── Apuntes/
    │   ├── Actividades/
    │   └── Proyecto/
    └── Seguridad y Alta Disponibilidad/
        ├── Apuntes/
        ├── Actividades/
        └── Proyecto/

    Puedes realizar las capturas en Windows, macOS o Linux.

    3. Objetivos

    Al finalizar la actividad deberás saber:

    • Crear un archivo README.md.
    • Escribir títulos y subtítulos.
    • Crear párrafos y listas.
    • Utilizar negrita y cursiva.
    • Insertar imágenes.
    • Crear enlaces.
    • Mostrar correctamente una estructura de carpetas.
    • Visualizar un documento Markdown.
    • Organizar los archivos de una documentación.

    4. Preparación de la actividad

    Crea una carpeta llamada:

    actividad-01-markdown

    Dentro de ella crea la siguiente estructura:

    actividad-01-markdown/
    ├── README.md
    └── img/

    El archivo README.md contendrá la documentación.

    La carpeta img contendrá las imágenes utilizadas en el documento.

    5. Herramientas

    Puedes utilizar:

    • Visual Studio Code para escribir el documento.
    • El explorador de archivos de tu sistema operativo.
    • La herramienta de captura de pantalla de Windows, macOS o Linux.

    No es necesario instalar programas adicionales.

    6. Contenido obligatorio del README

    Tu documento deberá contener los siguientes apartados.

    6.1 Título

    El documento comenzará con un título principal:

    # Cómo organizar archivos y carpetas en un ordenador

    6.2 Introducción

    Escribe un pequeño párrafo explicando por qué es importante mantener organizados los archivos.

    El texto debe estar redactado con tus propias palabras.

    6.3 Material necesario

    Crea una lista que indique lo necesario para seguir la guía.

    Ejemplo:

    ## Material necesario
    
    - Un ordenador.
    - Un sistema operativo.
    - Acceso al explorador de archivos.

    6.4 Procedimiento

    Explica cómo crear la estructura de carpetas.

    Debes dividir el procedimiento en pasos:

    ## Procedimiento
    
    ### Paso 1. Crear la carpeta principal
    
    Explicación del primer paso.
    
    ### Paso 2. Crear las carpetas de las asignaturas
    
    Explicación del segundo paso.
    
    ### Paso 3. Crear las subcarpetas
    
    Explicación del tercer paso.

    Cada paso deberá incluir:

    • Un subtítulo.
    • Una explicación.
    • Una captura de pantalla.

    6.5 Resultado final

    Incluye una captura en la que se vea la estructura completa de carpetas.

    Debajo de la captura, explica brevemente el resultado obtenido.

    6.6 Ventajas de organizar los archivos

    Incluye una lista con al menos tres ventajas.

    Por ejemplo:

    • Encontrar los archivos con mayor rapidez.
    • Evitar la pérdida de trabajos.
    • Separar los contenidos de cada asignatura.

    6.7 Enlace externo

    Añade un enlace a una página relacionada con la organización de archivos, Markdown o Visual Studio Code.

    La sintaxis es:

    [Texto que verá el lector](https://direccion-de-la-pagina.es)

    6.8 Conclusiones

    Escribe un párrafo final respondiendo a estas preguntas:

    • ¿Qué has aprendido?
    • ¿Qué parte te ha resultado más fácil?
    • ¿Qué dificultad has encontrado?
    • ¿Para qué crees que puede servir un README?

    No debes copiar las preguntas. Utilízalas como orientación para redactar tu conclusión.

    7. Cómo insertar las imágenes

    Guarda todas las capturas dentro de la carpeta img.

    Utiliza nombres descriptivos y sin espacios:

    img/
    ├── carpeta-principal.png
    ├── carpetas-asignaturas.png
    └── resultado-final.png

    Para insertar una imagen en el README utiliza:

    ![Descripción de la imagen](img/carpeta-principal.png)

    No utilices nombres como:

    Captura de pantalla 2026-09-09.png
    foto1.png
    imagen nueva final.png

    Utiliza nombres que permitan reconocer el contenido:

    crear-carpeta-principal.png
    estructura-asignaturas.png
    resultado-final.png

    8. Requisitos de las capturas

    Las capturas deberán:

    • Mostrar únicamente la zona necesaria.
    • Tener suficiente calidad para poder leerlas.
    • Estar relacionadas con la explicación.
    • Aparecer después del paso que representan.
    • No mostrar contraseñas ni información personal.
    • Incluir un texto alternativo descriptivo.

    No se admitirán capturas sin una explicación asociada.

    9. Formato Markdown obligatorio

    El documento deberá utilizar, como mínimo:

    • Un título principal.
    • Cinco subtítulos.
    • Una lista con viñetas.
    • Una lista numerada.
    • Texto en negrita.
    • Texto en cursiva.
    • Tres imágenes.
    • Un enlace externo.
    • Un bloque con la estructura de carpetas.

    10. Visualización del documento

    Abre README.md con Visual Studio Code.

    Para mostrar su vista previa:

    • En Windows y Linux: Ctrl + Shift + V
    • En macOS: Cmd + Shift + V

    También puedes utilizar el botón de vista previa situado en la esquina superior derecha del editor.

    Antes de entregar, comprueba que:

    • Los títulos se muestran correctamente.
    • Las imágenes aparecen.
    • El enlace funciona.
    • No se ven los símbolos de Markdown en la vista previa.
    • No hay apartados vacíos.

    11. Entrega

    Debes entregar una carpeta comprimida llamada:

    apellido-nombre-actividad-01.zip

    Ejemplo:

    garcia-ana-actividad-01.zip

    El archivo comprimido deberá contener:

    actividad-01-markdown/
    ├── README.md
    └── img/
        ├── crear-carpeta-principal.png
        ├── estructura-asignaturas.png
        └── resultado-final.png

    No debes entregar un documento Word ni convertir el README a PDF.

    12. Lista de comprobación

    Antes de entregar, comprueba lo siguiente:

    • El archivo se llama README.md.
    • El README contiene un título principal.
    • He utilizado títulos y subtítulos.
    • He incluido al menos tres imágenes.
    • Las imágenes están guardadas en img.
    • Todas las imágenes se muestran en la vista previa.
    • He utilizado negrita y cursiva.
    • He creado una lista.
    • He añadido un enlace.
    • He escrito una conclusión personal.
    • He revisado la ortografía.
    • La carpeta tiene el nombre solicitado.