Sistemas informáticos

Appearance

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.

Algunos ejemplos habituales son:

  • instrucciones de instalación y configuración;
  • procedimientos de administración y mantenimiento;
  • documentación de aplicaciones y proyectos;
  • documentación de APIs;
  • manuales de usuario;
  • documentación de incidencias;
  • documentación de código;
  • guías de despliegue;
  • documentación de redes e infraestructuras.

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, destinada a explicar el funcionamiento de una aplicación o sistema;
  • documentación de instalación, con los requisitos y pasos necesarios para instalar software;
  • documentación de configuración, que describe los parámetros necesarios para adaptar un sistema;
  • documentación de administración, destinada al mantenimiento y gestión de sistemas;
  • documentación de desarrollo, relacionada con código, APIs, dependencias, compilación o despliegue;
  • documentación de procedimientos, que describe de forma ordenada cómo realizar una determinada tarea;
  • documentación de incidencias, donde se registran problemas, diagnósticos y soluciones aplicadas.

Un mismo proyecto puede contener varios de estos tipos de documentación.

Herramientas para crear documentación ​

La elaboración de documentación técnica requiere utilizar diferentes tipos de software.

No existe una única herramienta válida para todos los entornos. La elección depende de factores como el propósito de la documentación, el sistema operativo utilizado, las necesidades de colaboración, el formato de publicación o las herramientas empleadas por la organización.

Tipos de software ​

Las aplicaciones pueden clasificarse atendiendo a su propósito.

Por ejemplo:

  • 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 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.

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.

INFO

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.

Herramientas utilizadas en la unidad ​

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

Terminal ​

La 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 ​

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 ​

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 ​

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 ​

GitHub es una plataforma que permite alojar repositorios Git y facilita la colaboración en proyectos.

Utilizaremos GitHub para alojar nuestros repositorios remotos y sincronizarlos a través de Internet.

GitHub Pages ​

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.

Flujo de trabajo de documentación ​

Las herramientas anteriores no se utilizarán de manera aislada. Formarán parte de un mismo flujo de trabajo.

De forma simplificada:

text
Archivos y directorios
        ↓
Visual Studio Code
        ↓
     Markdown
        ↓
       Git
        ↓
     GitHub
        ↓
  GitHub Pages

Durante la unidad aprenderemos progresivamente cada una de estas partes.

El objetivo final será disponer de un procedimiento que permita:

  1. Organizar los archivos de un proyecto.
  2. Elaborar documentación utilizando Markdown.
  3. Editarla con Visual Studio Code.
  4. Registrar sus cambios utilizando Git.
  5. Alojar el repositorio en GitHub.
  6. Publicar la documentación en Internet utilizando GitHub Pages.

Este mismo flujo de trabajo se utilizará posteriormente para documentar las prácticas realizadas durante el módulo de Sistemas informáticos.