Búsqueda de documentación

En informática es habitual encontrarse con tecnologías desconocidas, comandos que no recordamos, errores inesperados o configuraciones que necesitamos realizar por primera vez.

Por este motivo, una competencia fundamental de cualquier profesional informático es saber localizar, interpretar y verificar información técnica.

Actualmente disponemos de diferentes herramientas para buscar información y de numerosas fuentes en las que consultarla.

Herramientas de búsqueda

Para localizar información técnica podemos utilizar principalmente buscadores y herramientas de inteligencia artificial.

Buscadores

Los buscadores permiten localizar documentación, páginas oficiales, foros, artículos y otros recursos publicados en Internet.

Una búsqueda técnica debería describir con suficiente precisión aquello que queremos conseguir.

Por ejemplo:

Ubuntu 24.04 file permissions chmod

será normalmente más útil que:

problema permisos

También podemos restringir una búsqueda a un determinado sitio web mediante el operador site::

site:documentation.ubuntu.com file permissions

Esto resulta especialmente útil cuando queremos localizar información publicada en una fuente concreta, como la documentación oficial de una tecnología.

Los resultados de un buscador pueden conducirnos a diferentes tipos de fuentes:

• Documentación oficial.
• Foros y comunidades técnicas.
• Repositorios de código.
• Sistemas de preguntas y respuestas.
• Blogs y artículos.
• Vídeos.

Estas fuentes pueden contener información muy útil, pero debemos tener en cuenta su procedencia, fecha y versión de la tecnología utilizada.

Inteligencia artificial

Las herramientas de inteligencia artificial permiten realizar consultas utilizando lenguaje natural y obtener respuestas adaptadas al problema que estamos intentando resolver.

Por ejemplo, podemos utilizarlas para:

• Consultar cómo realizar una determinada tarea.
• Obtener información sobre un comando.
• Interpretar mensajes de error y salidas de terminal.
• Revisar un fragmento de código.
• Analizar una captura de pantalla.
• Comparar diferentes alternativas.
• Localizar posibles causas de un problema.
• Obtener indicaciones para continuar un procedimiento.

A diferencia de un buscador, que normalmente nos conduce a diferentes fuentes de información, una herramienta de inteligencia artificial puede proponer directamente una posible solución.

Sin embargo, una respuesta proporcionada por una herramienta de inteligencia artificial no constituye documentación oficial y puede contener información incorrecta, incompleta o no adecuada para nuestro entorno.

Proporcionar contexto

La calidad de una respuesta depende en gran medida de la información proporcionada.

Una consulta como:

No funciona el comando 'cp'

aporta muy poca información.

En cambio, podemos proporcionar datos como:

• Qué queremos conseguir.
• Qué sistema operativo estamos utilizando.
• Qué versión utilizamos.
• Qué comando hemos ejecutado.
• Qué resultado esperábamos.
• Qué resultado hemos obtenido.
• Qué mensaje de error aparece.

Por ejemplo:

Estoy utilizando Ubuntu 24.04.

Quiero copiar el archivo informe.txt al directorio /opt/docs
utilizando la terminal.

Al ejecutar:

cp informe.txt /opt/docs

obtengo el error:

Permission denied

¿Por qué ocurre y cómo puedo solucionarlo?

Cuanto mejor sea el contexto proporcionado, más útil podrá ser la respuesta obtenida.

Capturas de pantalla

En muchas ocasiones resulta más sencillo mostrar directamente el problema.

Las herramientas de inteligencia artificial capaces de analizar imágenes permiten adjuntar, por ejemplo:

• Capturas de mensajes de error.
• Ventanas de configuración.
• Resultados mostrados por una aplicación.
• Salidas de terminal.
• Interfaces de administración.
• Fragmentos de código visibles en pantalla.

Una captura puede proporcionar información que sería difícil o lento describir manualmente.

Cuando la información pueda copiarse directamente como texto, como un comando, un mensaje de error o una salida de terminal, será preferible proporcionar el texto en lugar de una captura de pantalla.

Antes de adjuntar una imagen debemos comprobar que no contiene información privada o sensible, como contraseñas, claves, tokens, datos personales o información confidencial.

Proporciona contexto

Adjuntar una captura no impide añadir una explicación.

Indicar qué estabas intentando hacer, qué resultado esperabas y qué problema has encontrado facilita considerablemente el diagnóstico.

Fuentes de información

Las herramientas de búsqueda nos permiten localizar información, pero debemos valorar de dónde procede la información encontrada.

Documentación oficial

La documentación oficial es la documentación publicada y mantenida por los responsables de una tecnología, aplicación o proyecto.

Puede incluir:

• Instrucciones de instalación.
• Guías de utilización.
• Referencias de comandos.
• Documentación de APIs.
• Ejemplos.
• Requisitos.
• Notas sobre versiones.
• Procedimientos de configuración.

Durante el módulo utilizaremos, entre otras, documentación oficial de Ubuntu, Microsoft, Visual Studio Code, Git y GitHub.

La documentación oficial resulta especialmente importante cuando necesitamos:

• Confirmar la sintaxis exacta de un comando.
• Comprobar la compatibilidad entre versiones.
• Conocer los requisitos de una aplicación.
• Consultar las opciones disponibles.
• Verificar que un procedimiento continúa siendo válido.
• Trabajar con configuraciones que puedan afectar a la seguridad o al sistema.

Linux Mint y Ubuntu

Linux Mint 22.x está basado en Ubuntu 24.04 LTS.

Por tanto, la documentación de Ubuntu será generalmente aplicable a Linux Mint, aunque para cuestiones específicas de Mint conviene consultar su propia documentación.

Manuales y ayuda integrada

Muchas herramientas incorporan sus propios mecanismos de ayuda.

En sistemas GNU/Linux, numerosos comandos disponen de páginas de manual que pueden consultarse mediante:

man comando

Por ejemplo:

man cp

También es habitual obtener una ayuda resumida mediante:

comando --help

Por ejemplo:

cp --help

Estas herramientas permiten consultar directamente la sintaxis, las opciones y el funcionamiento de los comandos sin necesidad de abandonar la terminal.

Otras fuentes

Además de la documentación oficial podemos encontrar información técnica en otras fuentes:

• Foros especializados.
• Sistemas de preguntas y respuestas.
• Repositorios de código.
• Blogs técnicos.
• Artículos.
• Vídeos.
• Comunidades de desarrolladores.

Estas fuentes pueden resultar especialmente útiles para encontrar ejemplos, problemas similares y soluciones utilizadas por otros usuarios.

Sin embargo, debemos comprobar siempre su procedencia, fecha y versión de la tecnología utilizada.

Una solución válida para una versión anterior de un sistema puede haber quedado obsoleta.

Verificación de la información

La información obtenida mediante inteligencia artificial, buscadores, documentación, foros u otras fuentes debe comprobarse antes de utilizarla.

Debemos verificar que sea adecuada para nuestro sistema operativo, versión y tecnología utilizada, y comprender las consecuencias de los comandos que vamos a ejecutar.

Cuando encontremos una posible solución mediante una herramienta de inteligencia artificial, un foro, un artículo u otra fuente, será recomendable contrastarla con la documentación oficial o con los mecanismos de ayuda disponibles.

Antes de ejecutar un comando

Comprueba qué hace, sobre qué recursos actúa y si modifica o elimina información.

Presta especial atención a los comandos que utilizan sudo o requieren privilegios de administrador.

Referencias utilizadas

Cuando para realizar una práctica sea necesario consultar documentación externa, se deberán indicar las fuentes utilizadas.

Para cada fuente será suficiente proporcionar su nombre y un enlace al recurso consultado.

Por ejemplo:

## Referencias

- [Ubuntu documentation](https://documentation.ubuntu.com/).
- [Git documentation](https://git-scm.com/doc).

Utiliza preferentemente fuentes oficiales y comprueba que la información consultada corresponde a la versión de la tecnología utilizada.

Cuando una herramienta de inteligencia artificial nos haya conducido hasta una fuente técnica, se indicará como referencia la documentación finalmente utilizada para comprobar la información, no la conversación mantenida con la herramienta.

Durante el resto del módulo

La búsqueda de documentación técnica será una actividad transversal durante todo el módulo.

En las prácticas no se proporcionarán necesariamente todos los comandos o procedimientos necesarios. Parte del trabajo consistirá en localizar la información necesaria, comprobar que es adecuada para el entorno utilizado y aplicarla correctamente.

Ejemplo de búsqueda de información

Supongamos que tenemos la siguiente estructura:

ud1/
├── index.md
└── images/

Queremos utilizar el terminal para realizar una copia completa del directorio ud1 y de todo su contenido con el nombre ud2, obteniendo:

ud1/
├── index.md
└── images/

ud2/
├── index.md
└── images/

No conocemos qué comando debemos utilizar ni cómo realizar esta operación.

Búsqueda mediante inteligencia artificial

Podemos describir directamente nuestra necesidad:

Estoy utilizando Ubuntu 24.04.

Tengo un directorio llamado ud1 que contiene un archivo index.md
y un subdirectorio images.

Quiero utilizar el terminal para copiar el directorio completo y
todo su contenido creando una copia llamada ud2.

¿Cómo puedo hacerlo?

La herramienta de inteligencia artificial puede proponernos una solución similar a:

cp -r ud1 ud2

Además, puede explicarnos que cp permite copiar archivos y directorios y que la opción -r realiza la copia de forma recursiva.

Sin embargo, no ejecutaremos todavía el comando. Antes comprobaremos esta información utilizando documentación técnica.

Búsqueda mediante un buscador

También podemos partir directamente de nuestra necesidad utilizando un buscador:

Ubuntu terminal copy directory and contents

Entre los resultados podemos encontrar documentación, foros, artículos y páginas en las que otros usuarios han resuelto problemas similares.

Estas fuentes pueden permitirnos descubrir que podemos utilizar el comando cp y que necesitamos realizar una copia recursiva.

Una vez identificado el comando, podemos realizar búsquedas más precisas:

Ubuntu cp recursive directory

Búsqueda de documentación oficial

Una vez sabemos que el comando que debemos investigar es cp, podemos buscar su documentación oficial.

Una búsqueda general puede devolver resultados de numerosos sitios web:

cp command documentation

Podemos utilizar site: para limitar los resultados a un dominio oficial. Por ejemplo:

site:gnu.org cp recursive

De esta forma podemos localizar la documentación oficial de GNU Coreutils, donde se encuentra documentado el comando cp.

En ella podemos comprobar:

• Para qué sirve cp.
• Su sintaxis.
• Las opciones disponibles.
• Cómo realizar copias recursivas.

Consulta mediante man

También podemos consultar directamente la documentación disponible en nuestro sistema:

man cp

Podemos buscar dentro de la página del manual la opción relacionada con la copia recursiva.

Otra posibilidad es consultar la ayuda resumida:

cp --help

La documentación nos permite comprobar que la opción -r (--recursive) permite copiar directorios y su contenido de forma recursiva.

Aplicación de la solución

Después de localizar y verificar la información ya podemos ejecutar:

cp -r ud1 ud2

Antes de hacerlo debemos comprender:

• Que cp es el comando que realizará la copia.
• Que -r permite copiar el directorio y todo su contenido.
• Que ud1 es el origen.
• Que ud2 será el destino de la copia.

Después de ejecutar el comando podemos comprobar que hemos obtenido el resultado esperado:

ud1/
├── index.md
└── images/

ud2/
├── index.md
└── images/

Este proceso nos ha permitido partir de una necesidad que no sabíamos resolver, localizar una posible solución y comprobarla mediante documentación técnica antes de aplicarla.