Lenguajes y Fundamentos de Programación · DEV-110

Documentación técnica como código

Manuales que se versionan junto al código, se revisan como un cambio más y se publican al confirmar.

Próximamente Iniciación 7 módulos · 34 clases

Formato asíncrono Desarrollo, Ingeniería / Industria Git, MkDocs

DESARROLLO

Lo que aprenderás

Escribir documentación técnica en Markdown con una estructura de secciones navegable
Montar un sitio de documentación con MkDocs y el tema Material configurando navegación y búsqueda
Versionar la documentación en Git junto al proyecto y revisarla mediante pull request
Publicar el sitio automáticamente en cada cambio confirmado en la rama principal
Incluir fragmentos de código, diagramas y capturas de forma que no se queden desactualizados
Mantener varias versiones publicadas del manual correspondientes a versiones del producto
Definir qué documentos debe tener el proyecto y quién es responsable de cada uno

Contenido del curso

7 módulos · 34 clases en vídeo · práctica guiada en cada módulo

Módulo 1 · Documentación como código 5 clases

Por qué falla el documento en carpeta compartida
Qué documentos necesita un proyecto técnico
El repositorio como origen único de verdad
Herramientas del curso y preparación del entorno
Primer documento en Markdown

Módulo 2 · Escribir en Markdown 5 clases

Sintaxis esencial y buenas prácticas
Bloques de código, avisos y tablas
Enlaces internos y estructura de ficheros
Imágenes y su organización
Escribir para quien no conoce el proyecto

Módulo 3 · MkDocs 5 clases

Instalación y primer sitio local
Configuración de navegación y secciones
Tema Material y personalización
Búsqueda, índice y navegación lateral
Vista previa en vivo mientras se escribe

Módulo 4 · Contenido que no envejece 5 clases

Incluir fragmentos desde ficheros de código reales
Diagramas versionables con Mermaid
Capturas: cuándo usarlas y cómo mantenerlas
Ejemplos ejecutables y comprobables
Enlaces rotos y su detección automática

Módulo 5 · Flujo de trabajo del equipo 5 clases

Documentación en la misma rama que el cambio
Revisión por pull request y comentarios
Plantillas de documento y guía de estilo
Responsables por sección
Documentación mínima exigible para aceptar un cambio

Módulo 6 · Publicación 5 clases

Construcción del sitio y comprobación previa
Publicación automática al confirmar en la rama principal
Dominio propio y acceso restringido
Varias versiones publicadas del manual
Archivo de versiones antiguas

Módulo 7 · Caso práctico de cierre 4 clases

Documentar un proyecto existente de principio a fin
Estructura de secciones y guía de incorporación
Publicación automática en funcionamiento
Revisión con una persona ajena al proyecto

Requisitos

No se necesita experiencia previa en documentación técnica
Manejo básico de Git a nivel de confirmar cambios y trabajar con ramas
Un editor de texto y una cuenta en una plataforma de repositorios para publicar el sitio

Descripción

La documentación en un procesador de textos en una carpeta compartida siempre acaba igual: desactualizada, duplicada en tres versiones y sin que nadie sepa cuál manda. Mientras tanto el proyecto cambia cada semana, y quien llega nuevo pierde días preguntando cosas que deberían estar escritas.

Este curso trata la documentación como parte del código. Markdown en el repositorio, MkDocs para publicar un sitio navegable con búsqueda, revisión por pull request igual que un cambio de código, y publicación automática al confirmar. Se trabajan además los diagramas versionables, la inclusión de fragmentos de código reales y el mantenimiento de varias versiones del manual.

El resultado es un manual que está siempre donde está el proyecto, que se revisa antes de entrar y que se publica solo. Reduce el tiempo de incorporación de gente nueva y sirve tanto para documentación interna como para un manual de usuario o una guía de despliegue.

¿Para quién es este curso?

Desarrolladores que reciben proyectos sin documentar y pierden días entendiendo lo que hay
Equipos de ingeniería que mantienen manuales de despliegue y de operación en ficheros dispersos
Responsables técnicos que quieren reducir el tiempo de incorporación de personal nuevo