Documentación técnica

La documentación técnica recoge y organiza la información necesaria para comprender, utilizar, configurar, mantener o resolver problemas relacionados con un sistema, una aplicación o una infraestructura informática.

En un entorno profesional, realizar una tarea técnica no suele ser suficiente. También es necesario documentar qué se ha hecho, cómo se ha hecho y qué recursos se han utilizado, de forma que el trabajo pueda ser consultado posteriormente por nosotros mismos o por otros miembros del equipo.

Durante esta unidad aprenderemos a crear documentación técnica utilizando herramientas y tecnologías habituales en entornos de desarrollo de software.

La documentación en un entorno profesional

La documentación forma parte del trabajo cotidiano de administradores de sistemas, desarrolladores y otros profesionales de las tecnologías de la información.

Una buena documentación debe ser clara, precisa, estructurada, actualizada y fácilmente accesible.

Además, debe permitir que un procedimiento pueda ser reproducido. Por ejemplo, una guía de instalación debería proporcionar la información necesaria para que otro técnico pueda realizar correctamente la misma instalación.

Documentar forma parte del trabajo

Durante el módulo no consideraremos la documentación como una tarea independiente realizada al finalizar una práctica. La documentación formará parte del propio proceso de trabajo.

Tipos de documentación técnica

La documentación puede clasificarse de diferentes formas dependiendo de su finalidad y de las personas a las que está dirigida. Podemos encontrar, entre otras:

Documentación de usuario

Está destinada a explicar el funcionamiento de una aplicación o sistema.

Explorador de archivos de Windows

La documentación del Explorador de archivos explica cómo utilizar esta herramienta de Windows para acceder, organizar y gestionar archivos y carpetas.

Documentación de instalación

Contiene los requisitos y pasos necesarios para instalar software.

Instalación de Ubuntu Desktop

La guía de instalación de Ubuntu Desktop 24.04 LTS describe paso a paso el proceso de instalación del sistema operativo.

Documentación de configuración

Describe los parámetros necesarios para adaptar un sistema o aplicación.

Configuración de Visual Studio Code

La documentación de configuración de Visual Studio Code explica cómo modificar las opciones del editor para adaptarlo a las necesidades del usuario.

Documentación de administración

Está destinada al mantenimiento y gestión de sistemas o servicios.

Gestión de repositorios en GitHub

La documentación sobre repositorios de GitHub reúne información para crear, configurar y administrar repositorios.

Documentación de GitHub en Markdown

Las páginas de GitHub Docs permiten consultar el archivo Markdown original mediante la opción View as Markdown.

Esto permite observar cómo una documentación profesional utiliza Markdown para estructurar su contenido.

El ejemplo de la imagen se corresponde con la sección Creating a repository from a template.

Documentación de desarrollo

Está relacionada con código, lenguajes de programación, APIs, dependencias, compilación o despliegue.

Desarrollo con JavaScript

La JavaScript Guide de MDN proporciona documentación para desarrollar aplicaciones utilizando JavaScript, incluyendo su sintaxis, estructuras de control, funciones, objetos y otras características del lenguaje.

Documentación de referencia

Proporciona información detallada y estructurada sobre los elementos, comandos, funciones, opciones o características de una tecnología.

Referencia de Git

La documentación de referencia de Git describe los comandos disponibles, sus opciones, parámetros y funcionamiento.

Documentación de incidencias

Registra problemas detectados en un sistema o servicio, incluyendo información sobre su diagnóstico, evolución y resolución.

Incidencias de Cloudflare

El historial de Cloudflare Status permite consultar incidencias reales que han afectado a sus servicios y seguir su evolución hasta su resolución.

Los tipos de documentación no son excluyentes

Un proyecto normalmente contiene varios tipos de documentación, ya que cada uno responde a diferentes necesidades y usuarios.

Además, esta clasificación no pretende ser exhaustiva. Dependiendo del proyecto pueden existir otros tipos de documentación, como documentación de seguridad, arquitectura, pruebas o mantenimiento, o categorías que combinen varios de los anteriores.

Tipos de software

Para crear y gestionar documentación técnica pueden utilizarse diferentes tipos de aplicaciones y servicios, cada uno con una función específica dentro del flujo de trabajo. Entre los más habituales encontramos:

• Editores de texto y código, para crear y modificar archivos.
• Herramientas ofimáticas, para elaborar documentos, hojas de cálculo o presentaciones.
• Navegadores web, para acceder a aplicaciones y documentación disponible en Internet.
• Sistemas de control de versiones, para gestionar los cambios realizados sobre archivos.
• Plataformas de colaboración, para compartir proyectos y trabajar con otros usuarios.
• Herramientas y servicios de publicación, para publicar y distribuir contenidos a través de Internet.
• Herramientas de comunicación, como el correo electrónico y la mensajería.
• Utilidades del sistema, para realizar tareas de administración y mantenimiento.
• Aplicaciones de propósito específico, diseñadas para resolver necesidades concretas de determinados entornos profesionales.

Antes de seleccionar una aplicación debemos identificar qué problema necesitamos resolver y qué características debe proporcionar la herramienta.

Nuestro stack

Durante esta unidad utilizaremos varias herramientas y tecnologías que, combinadas, permitirán crear, gestionar, versionar y publicar documentación técnica.

• Terminal. Proporciona una interfaz de línea de comandos para interactuar con el sistema operativo. La utilizaremos inicialmente para trabajar con archivos y directorios y, posteriormente, para ejecutar algunas de las herramientas de la unidad.

• Visual Studio Code. Es un editor de código fuente que permite trabajar con numerosos tipos de archivos y lenguajes. Lo utilizaremos como editor principal para crear y modificar nuestros archivos de documentación.

• Markdown. Es un lenguaje de marcado ligero que permite estructurar y dar formato a documentos utilizando texto plano. Será el formato principal utilizado para redactar la documentación.

• Git. Es un sistema de control de versiones distribuido. Nos permitirá registrar los cambios realizados en nuestros documentos y mantener un historial de su evolución.

• GitHub. Es una plataforma que permite alojar repositorios Git y facilita la colaboración en proyectos. La utilizaremos para alojar nuestros repositorios remotos y sincronizarlos a través de Internet.

• GitHub Pages. Es un servicio de alojamiento de sitios web estáticos integrado en GitHub. Lo utilizaremos para publicar en Internet la documentación almacenada en nuestros repositorios.

Estas herramientas se introducirán progresivamente durante la unidad y formarán parte de un mismo flujo de trabajo.

Licencias de software

El software también puede clasificarse según las condiciones bajo las que puede utilizarse, modificarse y distribuirse.

Estas condiciones se establecen mediante una licencia de software.

Podemos encontrar, entre otras posibilidades:

• Software propietario, cuyo uso, modificación o distribución está limitado por las condiciones establecidas por su propietario.
• Software libre, cuya licencia garantiza determinadas libertades para utilizarlo, estudiarlo, modificarlo y redistribuirlo.
• Software de código abierto, cuyo código fuente está disponible bajo una licencia que permite su utilización, modificación y redistribución en las condiciones establecidas por dicha licencia.

Dentro del software libre y de código abierto existen numerosas licencias, como GPL, MIT o Apache License 2.0, cada una con sus propias condiciones.

Free software

El término inglés free software se traduce como software libre, no como software gratuito. La palabra free hace referencia en este contexto a las libertades que proporciona la licencia para utilizar, estudiar, modificar y redistribuir el software.

Por tanto, que una aplicación sea gratuita no significa necesariamente que sea software libre. Del mismo modo, que su código fuente pueda consultarse no implica por sí solo que pueda modificarse o redistribuirse libremente.

Para conocer las condiciones reales de utilización de un programa debemos consultar su licencia.

Requisitos y elección de herramientas

Antes de utilizar una aplicación también debemos comprobar sus requisitos y valorar si resulta adecuada para el entorno en el que vamos a trabajar.

Entre otros aspectos podemos considerar:

• Sistemas operativos compatibles.
• Requisitos de hardware.
• Dependencias necesarias.
• Versiones disponibles.
• Licencia.
• Coste.
• Formatos soportados.
• Posibilidad de trabajar de forma local o a través de Internet.
• Posibilidades de colaboración.
• Integración con otras herramientas.
• Mantenimiento y actualizaciones.
• Documentación disponible.

En un entorno profesional, la elección de software debe responder a las necesidades reales del proyecto o de la organización, y no únicamente a las preferencias personales del usuario.

Requisitos de nuestro stack

Las herramientas que utilizaremos durante la unidad tienen requisitos diferentes.

Algunas, como Visual Studio Code o Git, deben instalarse en el equipo y requieren comprobar su compatibilidad con el sistema operativo y sus requisitos de instalación.

Otras, como GitHub y GitHub Pages, son servicios accesibles a través de Internet y requieren principalmente un navegador web, conexión a Internet y una cuenta de usuario.

Elección de nuestro stack

La elección de este stack responde a varios criterios:

• Permite crear, versionar, almacenar y publicar documentación utilizando un mismo flujo de trabajo.
• Facilita centrarse principalmente en el contenido, utilizando Markdown para aplicar formato mediante una sintaxis sencilla.
• Permite realizar una maquetación sencilla de la documentación.
• Permite aplicar diferentes estilos de presentación sin necesidad de modificar el contenido original.
• Facilita el control de los cambios realizados en la documentación mediante Git.
• Permite almacenar y compartir la documentación utilizando repositorios remotos en GitHub.
• Permite publicar la documentación en Internet mediante GitHub Pages.
• Permite acceder a la documentación publicada desde cualquier navegador web con conexión a Internet.
• Puede utilizarse sin coste para las necesidades de esta unidad y algunas de sus herramientas son software libre o de código abierto.
• Utiliza herramientas y tecnologías habituales en entornos de desarrollo de software.
• Dispone de abundante documentación técnica para consultar su funcionamiento.

Flujo de trabajo de documentación

En un entorno profesional, las herramientas utilizadas para realizar una tarea no suelen emplearse de manera aislada. Normalmente forman parte de un flujo de trabajo en el que cada herramienta interviene en una determinada fase del proceso.

Un flujo de trabajo establece cómo se organiza y desarrolla una tarea, definiendo una secuencia de acciones y la forma en que las diferentes herramientas se relacionan entre sí.

En la creación de documentación técnica, por ejemplo, podemos utilizar una herramienta para redactar los documentos, otra para controlar sus cambios, una plataforma para almacenarlos y compartirlos y, finalmente, un servicio para publicarlos.

La definición de un flujo de trabajo permite organizar el proceso, utilizar las herramientas de forma coherente y facilitar que el trabajo pueda repetirse y mantenerse.

Flujo de trabajo de nuestro stack

Durante la unidad utilizaremos las herramientas de nuestro stack siguiendo, de forma simplificada, el siguiente flujo de trabajo:

Archivos y directorios
[Organización de la documentación]
        ↓
Visual Studio Code
[Edición de los archivos]
        ↓
Markdown
[Estructura y formato del contenido]
        ↓
Git
[Control de versiones]
        ↓
GitHub
[Alojamiento del repositorio remoto]
        ↓
GitHub Pages
[Publicación de la documentación]